diff options
Diffstat (limited to 'core/src/fxge/Microsoft SDK/include/DWrite.h')
| -rw-r--r-- | core/src/fxge/Microsoft SDK/include/DWrite.h | 10012 |
1 files changed, 5006 insertions, 5006 deletions
diff --git a/core/src/fxge/Microsoft SDK/include/DWrite.h b/core/src/fxge/Microsoft SDK/include/DWrite.h index 70f998a437..0374694f74 100644 --- a/core/src/fxge/Microsoft SDK/include/DWrite.h +++ b/core/src/fxge/Microsoft SDK/include/DWrite.h @@ -1,5006 +1,5006 @@ -//+--------------------------------------------------------------------------
-//
-// 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
-
-/// <summary>
-/// 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.
-/// </summary>
-enum DWRITE_FONT_FILE_TYPE
-{
- /// <summary>
- /// Font type is not recognized by the DirectWrite font system.
- /// </summary>
- DWRITE_FONT_FILE_TYPE_UNKNOWN,
-
- /// <summary>
- /// OpenType font with CFF outlines.
- /// </summary>
- DWRITE_FONT_FILE_TYPE_CFF,
-
- /// <summary>
- /// OpenType font with TrueType outlines.
- /// </summary>
- DWRITE_FONT_FILE_TYPE_TRUETYPE,
-
- /// <summary>
- /// OpenType font that contains a TrueType collection.
- /// </summary>
- DWRITE_FONT_FILE_TYPE_TRUETYPE_COLLECTION,
-
- /// <summary>
- /// Type 1 PFM font.
- /// </summary>
- DWRITE_FONT_FILE_TYPE_TYPE1_PFM,
-
- /// <summary>
- /// Type 1 PFB font.
- /// </summary>
- DWRITE_FONT_FILE_TYPE_TYPE1_PFB,
-
- /// <summary>
- /// Vector .FON font.
- /// </summary>
- DWRITE_FONT_FILE_TYPE_VECTOR,
-
- /// <summary>
- /// Bitmap .FON font.
- /// </summary>
- DWRITE_FONT_FILE_TYPE_BITMAP
-};
-
-/// <summary>
-/// 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.
-/// </summary>
-enum DWRITE_FONT_FACE_TYPE
-{
- /// <summary>
- /// OpenType font face with CFF outlines.
- /// </summary>
- DWRITE_FONT_FACE_TYPE_CFF,
-
- /// <summary>
- /// OpenType font face with TrueType outlines.
- /// </summary>
- DWRITE_FONT_FACE_TYPE_TRUETYPE,
-
- /// <summary>
- /// OpenType font face that is a part of a TrueType collection.
- /// </summary>
- DWRITE_FONT_FACE_TYPE_TRUETYPE_COLLECTION,
-
- /// <summary>
- /// A Type 1 font face.
- /// </summary>
- DWRITE_FONT_FACE_TYPE_TYPE1,
-
- /// <summary>
- /// A vector .FON format font face.
- /// </summary>
- DWRITE_FONT_FACE_TYPE_VECTOR,
-
- /// <summary>
- /// A bitmap .FON format font face.
- /// </summary>
- DWRITE_FONT_FACE_TYPE_BITMAP,
-
- /// <summary>
- /// Font face type is not recognized by the DirectWrite font system.
- /// </summary>
- DWRITE_FONT_FACE_TYPE_UNKNOWN
-};
-
-/// <summary>
-/// Specifies algorithmic style simulations to be applied to the font face.
-/// Bold and oblique simulations can be combined via bitwise OR operation.
-/// </summary>
-enum DWRITE_FONT_SIMULATIONS
-{
- /// <summary>
- /// No simulations are performed.
- /// </summary>
- DWRITE_FONT_SIMULATIONS_NONE = 0x0000,
-
- /// <summary>
- /// Algorithmic emboldening is performed.
- /// </summary>
- DWRITE_FONT_SIMULATIONS_BOLD = 0x0001,
-
- /// <summary>
- /// Algorithmic italicization is performed.
- /// </summary>
- DWRITE_FONT_SIMULATIONS_OBLIQUE = 0x0002
-};
-
-#ifdef DEFINE_ENUM_FLAG_OPERATORS
-DEFINE_ENUM_FLAG_OPERATORS(DWRITE_FONT_SIMULATIONS);
-#endif
-
-/// <summary>
-/// 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.
-/// </summary>
-enum DWRITE_FONT_WEIGHT
-{
- /// <summary>
- /// Predefined font weight : Thin (100).
- /// </summary>
- DWRITE_FONT_WEIGHT_THIN = 100,
-
- /// <summary>
- /// Predefined font weight : Extra-light (200).
- /// </summary>
- DWRITE_FONT_WEIGHT_EXTRA_LIGHT = 200,
-
- /// <summary>
- /// Predefined font weight : Ultra-light (200).
- /// </summary>
- DWRITE_FONT_WEIGHT_ULTRA_LIGHT = 200,
-
- /// <summary>
- /// Predefined font weight : Light (300).
- /// </summary>
- DWRITE_FONT_WEIGHT_LIGHT = 300,
-
- /// <summary>
- /// Predefined font weight : Normal (400).
- /// </summary>
- DWRITE_FONT_WEIGHT_NORMAL = 400,
-
- /// <summary>
- /// Predefined font weight : Regular (400).
- /// </summary>
- DWRITE_FONT_WEIGHT_REGULAR = 400,
-
- /// <summary>
- /// Predefined font weight : Medium (500).
- /// </summary>
- DWRITE_FONT_WEIGHT_MEDIUM = 500,
-
- /// <summary>
- /// Predefined font weight : Demi-bold (600).
- /// </summary>
- DWRITE_FONT_WEIGHT_DEMI_BOLD = 600,
-
- /// <summary>
- /// Predefined font weight : Semi-bold (600).
- /// </summary>
- DWRITE_FONT_WEIGHT_SEMI_BOLD = 600,
-
- /// <summary>
- /// Predefined font weight : Bold (700).
- /// </summary>
- DWRITE_FONT_WEIGHT_BOLD = 700,
-
- /// <summary>
- /// Predefined font weight : Extra-bold (800).
- /// </summary>
- DWRITE_FONT_WEIGHT_EXTRA_BOLD = 800,
-
- /// <summary>
- /// Predefined font weight : Ultra-bold (800).
- /// </summary>
- DWRITE_FONT_WEIGHT_ULTRA_BOLD = 800,
-
- /// <summary>
- /// Predefined font weight : Black (900).
- /// </summary>
- DWRITE_FONT_WEIGHT_BLACK = 900,
-
- /// <summary>
- /// Predefined font weight : Heavy (900).
- /// </summary>
- DWRITE_FONT_WEIGHT_HEAVY = 900,
-
- /// <summary>
- /// Predefined font weight : Extra-black (950).
- /// </summary>
- DWRITE_FONT_WEIGHT_EXTRA_BLACK = 950,
-
- /// <summary>
- /// Predefined font weight : Ultra-black (950).
- /// </summary>
- DWRITE_FONT_WEIGHT_ULTRA_BLACK = 950
-};
-
-/// <summary>
-/// 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.
-/// </summary>
-enum DWRITE_FONT_STRETCH
-{
- /// <summary>
- /// Predefined font stretch : Not known (0).
- /// </summary>
- DWRITE_FONT_STRETCH_UNDEFINED = 0,
-
- /// <summary>
- /// Predefined font stretch : Ultra-condensed (1).
- /// </summary>
- DWRITE_FONT_STRETCH_ULTRA_CONDENSED = 1,
-
- /// <summary>
- /// Predefined font stretch : Extra-condensed (2).
- /// </summary>
- DWRITE_FONT_STRETCH_EXTRA_CONDENSED = 2,
-
- /// <summary>
- /// Predefined font stretch : Condensed (3).
- /// </summary>
- DWRITE_FONT_STRETCH_CONDENSED = 3,
-
- /// <summary>
- /// Predefined font stretch : Semi-condensed (4).
- /// </summary>
- DWRITE_FONT_STRETCH_SEMI_CONDENSED = 4,
-
- /// <summary>
- /// Predefined font stretch : Normal (5).
- /// </summary>
- DWRITE_FONT_STRETCH_NORMAL = 5,
-
- /// <summary>
- /// Predefined font stretch : Medium (5).
- /// </summary>
- DWRITE_FONT_STRETCH_MEDIUM = 5,
-
- /// <summary>
- /// Predefined font stretch : Semi-expanded (6).
- /// </summary>
- DWRITE_FONT_STRETCH_SEMI_EXPANDED = 6,
-
- /// <summary>
- /// Predefined font stretch : Expanded (7).
- /// </summary>
- DWRITE_FONT_STRETCH_EXPANDED = 7,
-
- /// <summary>
- /// Predefined font stretch : Extra-expanded (8).
- /// </summary>
- DWRITE_FONT_STRETCH_EXTRA_EXPANDED = 8,
-
- /// <summary>
- /// Predefined font stretch : Ultra-expanded (9).
- /// </summary>
- DWRITE_FONT_STRETCH_ULTRA_EXPANDED = 9
-};
-
-/// <summary>
-/// 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.
-/// </summary>
-enum DWRITE_FONT_STYLE
-{
- /// <summary>
- /// Font slope style : Normal.
- /// </summary>
- DWRITE_FONT_STYLE_NORMAL,
-
- /// <summary>
- /// Font slope style : Oblique.
- /// </summary>
- DWRITE_FONT_STYLE_OBLIQUE,
-
- /// <summary>
- /// Font slope style : Italic.
- /// </summary>
- DWRITE_FONT_STYLE_ITALIC
-
-};
-
-/// <summary>
-/// The informational string enumeration identifies a string in a font.
-/// </summary>
-enum DWRITE_INFORMATIONAL_STRING_ID
-{
- /// <summary>
- /// Unspecified name ID.
- /// </summary>
- DWRITE_INFORMATIONAL_STRING_NONE,
-
- /// <summary>
- /// Copyright notice provided by the font.
- /// </summary>
- DWRITE_INFORMATIONAL_STRING_COPYRIGHT_NOTICE,
-
- /// <summary>
- /// String containing a version number.
- /// </summary>
- DWRITE_INFORMATIONAL_STRING_VERSION_STRINGS,
-
- /// <summary>
- /// Trademark information provided by the font.
- /// </summary>
- DWRITE_INFORMATIONAL_STRING_TRADEMARK,
-
- /// <summary>
- /// Name of the font manufacturer.
- /// </summary>
- DWRITE_INFORMATIONAL_STRING_MANUFACTURER,
-
- /// <summary>
- /// Name of the font designer.
- /// </summary>
- DWRITE_INFORMATIONAL_STRING_DESIGNER,
-
- /// <summary>
- /// URL of font designer (with protocol, e.g., http://, ftp://).
- /// </summary>
- DWRITE_INFORMATIONAL_STRING_DESIGNER_URL,
-
- /// <summary>
- /// Description of the font. Can contain revision information, usage recommendations, history, features, etc.
- /// </summary>
- DWRITE_INFORMATIONAL_STRING_DESCRIPTION,
-
- /// <summary>
- /// 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.
- /// </summary>
- DWRITE_INFORMATIONAL_STRING_FONT_VENDOR_URL,
-
- /// <summary>
- /// 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.
- /// </summary>
- DWRITE_INFORMATIONAL_STRING_LICENSE_DESCRIPTION,
-
- /// <summary>
- /// URL where additional licensing information can be found.
- /// </summary>
- DWRITE_INFORMATIONAL_STRING_LICENSE_INFO_URL,
-
- /// <summary>
- /// 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").
- /// </summary>
- DWRITE_INFORMATIONAL_STRING_WIN32_FAMILY_NAMES,
-
- /// <summary>
- /// GDI-compatible subfamily name.
- /// </summary>
- DWRITE_INFORMATIONAL_STRING_WIN32_SUBFAMILY_NAMES,
-
- /// <summary>
- /// 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.
- /// </summary>
- DWRITE_INFORMATIONAL_STRING_PREFERRED_FAMILY_NAMES,
-
- /// <summary>
- /// Subfamily name preferred by the designer. This name is typically only present if it differs from the GDI-compatible subfamily name.
- /// </summary>
- DWRITE_INFORMATIONAL_STRING_PREFERRED_SUBFAMILY_NAMES,
-
- /// <summary>
- /// 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.
- /// </summary>
- DWRITE_INFORMATIONAL_STRING_SAMPLE_TEXT
-};
-
-
-/// <summary>
-/// The DWRITE_FONT_METRICS structure specifies the metrics of a font face that
-/// are applicable to all glyphs within the font face.
-/// </summary>
-struct DWRITE_FONT_METRICS
-{
- /// <summary>
- /// 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.
- /// </summary>
- UINT16 designUnitsPerEm;
-
- /// <summary>
- /// 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.
- /// </summary>
- UINT16 ascent;
-
- /// <summary>
- /// 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.
- /// </summary>
- UINT16 descent;
-
- /// <summary>
- /// 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.
- /// </summary>
- INT16 lineGap;
-
- /// <summary>
- /// 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.
- /// </summary>
- UINT16 capHeight;
-
- /// <summary>
- /// 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.
- /// </summary>
- UINT16 xHeight;
-
- /// <summary>
- /// 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.
- /// </summary>
- INT16 underlinePosition;
-
- /// <summary>
- /// The suggested underline thickness value of the font face in font design units.
- /// </summary>
- UINT16 underlineThickness;
-
- /// <summary>
- /// 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.
- /// </summary>
- INT16 strikethroughPosition;
-
- /// <summary>
- /// The suggested strikethrough thickness value of the font face in font design units.
- /// </summary>
- UINT16 strikethroughThickness;
-};
-
-/// <summary>
-/// The DWRITE_GLYPH_METRICS structure specifies the metrics of an individual glyph.
-/// The units depend on how the metrics are obtained.
-/// </summary>
-struct DWRITE_GLYPH_METRICS
-{
- /// <summary>
- /// 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').
- /// </summary>
- INT32 leftSideBearing;
-
- /// <summary>
- /// Specifies the X offset from the origin of the current glyph to the origin of the next glyph when writing horizontally.
- /// </summary>
- UINT32 advanceWidth;
-
- /// <summary>
- /// 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.
- /// </summary>
- INT32 rightSideBearing;
-
- /// <summary>
- /// 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.
- /// </summary>
- INT32 topSideBearing;
-
- /// <summary>
- /// 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).
- /// </summary>
- UINT32 advanceHeight;
-
- /// <summary>
- /// 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.
- /// </summary>
- INT32 bottomSideBearing;
-
- /// <summary>
- /// 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.
- /// </summary>
- INT32 verticalOriginY;
-};
-
-/// <summary>
-/// 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.
-/// </summary>
-struct DWRITE_GLYPH_OFFSET
-{
- /// <summary>
- /// 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.
- /// </summary>
- FLOAT advanceOffset;
-
- /// <summary>
- /// Offset in the ascent direction, i.e., the direction ascenders point. A positive ascender offset moves
- /// the glyph up (in pre-transform coordinates).
- /// </summary>
- FLOAT ascenderOffset;
-};
-
-/// <summary>
-/// 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.
-/// </summary>
-enum DWRITE_FACTORY_TYPE
-{
- /// <summary>
- /// 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.
- /// </summary>
- DWRITE_FACTORY_TYPE_SHARED,
-
- /// <summary>
- /// Objects created from the isolated factory do not interact with internal DirectWrite state from other components.
- /// </summary>
- 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<UINT32>(static_cast<UINT8>(d)) << 24) | \
- (static_cast<UINT32>(static_cast<UINT8>(c)) << 16) | \
- (static_cast<UINT32>(static_cast<UINT8>(b)) << 8) | \
- static_cast<UINT32>(static_cast<UINT8>(a)))
-
-interface IDWriteFontFileStream;
-
-/// <summary>
-/// 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.
-/// </summary>
-interface DWRITE_DECLARE_INTERFACE("727cad4e-d6af-4c9e-8a08-d695b11caa49") IDWriteFontFileLoader : public IUnknown
-{
- /// <summary>
- /// Creates a font file stream object that encapsulates an open file resource.
- /// The resource is closed when the last reference to fontFileStream is released.
- /// </summary>
- /// <param name="fontFileReferenceKey">Font file reference key that uniquely identifies the font file resource
- /// within the scope of the font loader being used.</param>
- /// <param name="fontFileReferenceKeySize">Size of font file reference key in bytes.</param>
- /// <param name="fontFileStream">Pointer to the newly created font file stream.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(CreateStreamFromKey)(
- __in_bcount(fontFileReferenceKeySize) void const* fontFileReferenceKey,
- UINT32 fontFileReferenceKeySize,
- __out IDWriteFontFileStream** fontFileStream
- ) PURE;
-};
-
-/// <summary>
-/// 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.
-/// </summary>
-interface DWRITE_DECLARE_INTERFACE("b2d9f3ec-c9fe-4a11-a2ec-d86208f7c0a2") IDWriteLocalFontFileLoader : public IDWriteFontFileLoader
-{
- /// <summary>
- /// Obtains the length of the absolute file path from the font file reference key.
- /// </summary>
- /// <param name="fontFileReferenceKey">Font file reference key that uniquely identifies the local font file
- /// within the scope of the font loader being used.</param>
- /// <param name="fontFileReferenceKeySize">Size of font file reference key in bytes.</param>
- /// <param name="filePathLength">Length of the file path string not including the terminated NULL character.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetFilePathLengthFromKey)(
- __in_bcount(fontFileReferenceKeySize) void const* fontFileReferenceKey,
- UINT32 fontFileReferenceKeySize,
- __out UINT32* filePathLength
- ) PURE;
-
- /// <summary>
- /// Obtains the absolute font file path from the font file reference key.
- /// </summary>
- /// <param name="fontFileReferenceKey">Font file reference key that uniquely identifies the local font file
- /// within the scope of the font loader being used.</param>
- /// <param name="fontFileReferenceKeySize">Size of font file reference key in bytes.</param>
- /// <param name="filePath">Character array that receives the local file path.</param>
- /// <param name="filePathSize">Size of the filePath array in character count including the terminated NULL character.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetFilePathFromKey)(
- __in_bcount(fontFileReferenceKeySize) void const* fontFileReferenceKey,
- UINT32 fontFileReferenceKeySize,
- __out_ecount_z(filePathSize) WCHAR* filePath,
- UINT32 filePathSize
- ) PURE;
-
- /// <summary>
- /// Obtains the last write time of the file from the font file reference key.
- /// </summary>
- /// <param name="fontFileReferenceKey">Font file reference key that uniquely identifies the local font file
- /// within the scope of the font loader being used.</param>
- /// <param name="fontFileReferenceKeySize">Size of font file reference key in bytes.</param>
- /// <param name="lastWriteTime">Last modified time of the font file.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetLastWriteTimeFromKey)(
- __in_bcount(fontFileReferenceKeySize) void const* fontFileReferenceKey,
- UINT32 fontFileReferenceKeySize,
- __out FILETIME* lastWriteTime
- ) PURE;
-};
-
-/// <summary>
-/// The interface for loading font file data.
-/// </summary>
-interface DWRITE_DECLARE_INTERFACE("6d4865fe-0ab8-4d91-8f62-5dd6be34a3e0") IDWriteFontFileStream : public IUnknown
-{
- /// <summary>
- /// Reads a fragment from a file.
- /// </summary>
- /// <param name="fragmentStart">Receives the pointer to the start of the font file fragment.</param>
- /// <param name="fileOffset">Offset of the fragment from the beginning of the font file.</param>
- /// <param name="fragmentSize">Size of the fragment in bytes.</param>
- /// <param name="fragmentContext">The client defined context to be passed to the ReleaseFileFragment.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- /// <remarks>
- /// IMPORTANT: ReadFileFragment() implementations must check whether the requested file fragment
- /// is within the file bounds. Otherwise, an error should be returned from ReadFileFragment.
- /// </remarks>
- STDMETHOD(ReadFileFragment)(
- __deref_out_bcount(fragmentSize) void const** fragmentStart,
- UINT64 fileOffset,
- UINT64 fragmentSize,
- __out void** fragmentContext
- ) PURE;
-
- /// <summary>
- /// Releases a fragment from a file.
- /// </summary>
- /// <param name="fragmentContext">The client defined context of a font fragment returned from ReadFileFragment.</param>
- STDMETHOD_(void, ReleaseFileFragment)(
- void* fragmentContext
- ) PURE;
-
- /// <summary>
- /// Obtains the total size of a file.
- /// </summary>
- /// <param name="fileSize">Receives the total size of the file.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- /// <remarks>
- /// 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).
- /// </remarks>
- STDMETHOD(GetFileSize)(
- __out UINT64* fileSize
- ) PURE;
-
- /// <summary>
- /// 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.
- /// </summary>
- /// <param name="lastWriteTime">Receives the last modifed time of the file in the format that represents
- /// the number of 100-nanosecond intervals since January 1, 1601 (UTC).</param>
- /// <returns>
- /// 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.
- /// </returns>
- STDMETHOD(GetLastWriteTime)(
- __out UINT64* lastWriteTime
- ) PURE;
-};
-
-/// <summary>
-/// The interface that represents a reference to a font file.
-/// </summary>
-interface DWRITE_DECLARE_INTERFACE("739d886a-cef5-47dc-8769-1a8b41bebbb0") IDWriteFontFile : public IUnknown
-{
- /// <summary>
- /// 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.
- /// </summary>
- /// <param name="fontFileReferenceKey">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.</param>
- /// <param name="fontFileReferenceKeySize">Size of font file reference key in bytes.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetReferenceKey)(
- __deref_out_bcount(*fontFileReferenceKeySize) void const** fontFileReferenceKey,
- __out UINT32* fontFileReferenceKeySize
- ) PURE;
-
- /// <summary>
- /// Obtains the file loader associated with a font file object.
- /// </summary>
- /// <param name="fontFileLoader">The font file loader associated with the font file object.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetLoader)(
- __out IDWriteFontFileLoader** fontFileLoader
- ) PURE;
-
- /// <summary>
- /// Analyzes a file and returns whether it represents a font, and whether the font type is supported by the font system.
- /// </summary>
- /// <param name="isSupportedFontType">TRUE if the font type is supported by the font system, FALSE otherwise.</param>
- /// <param name="fontFileType">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.</param>
- /// <param name="fontFaceType">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.</param>
- /// <param name="numberOfFaces">Number of font faces contained in the font file.</param>
- /// <returns>
- /// Standard HRESULT error code if there was a processing error during analysis.
- /// </returns>
- /// <remarks>
- /// 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.
- /// </remarks>
- STDMETHOD(Analyze)(
- __out BOOL* isSupportedFontType,
- __out DWRITE_FONT_FILE_TYPE* fontFileType,
- __out_opt DWRITE_FONT_FACE_TYPE* fontFaceType,
- __out UINT32* numberOfFaces
- ) PURE;
-};
-
-/// <summary>
-/// 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.
-/// </summary>
-#ifndef DWRITE_PIXEL_GEOMETRY_DEFINED
-enum DWRITE_PIXEL_GEOMETRY
-{
- /// <summary>
- /// The red, green, and blue color components of each pixel are assumed to occupy the same point.
- /// </summary>
- DWRITE_PIXEL_GEOMETRY_FLAT,
-
- /// <summary>
- /// 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.
- /// </summary>
- DWRITE_PIXEL_GEOMETRY_RGB,
-
- /// <summary>
- /// Each pixel comprises three vertical stripes, with blue on the left, green in the center, and
- /// red on the right.
- /// </summary>
- DWRITE_PIXEL_GEOMETRY_BGR
-};
-#define DWRITE_PIXEL_GEOMETRY_DEFINED
-#endif
-
-/// <summary>
-/// Represents a method of rendering glyphs.
-/// </summary>
-enum DWRITE_RENDERING_MODE
-{
- /// <summary>
- /// Specifies that the rendering mode is determined automatically based on the font and size.
- /// </summary>
- DWRITE_RENDERING_MODE_DEFAULT,
-
- /// <summary>
- /// 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.
- /// </summary>
- DWRITE_RENDERING_MODE_ALIASED,
-
- /// <summary>
- /// Specifies ClearType rendering with the same metrics as aliased text. Glyphs can only
- /// be positioned on whole-pixel boundaries.
- /// </summary>
- DWRITE_RENDERING_MODE_CLEARTYPE_GDI_CLASSIC,
-
- /// <summary>
- /// 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.
- /// </summary>
- DWRITE_RENDERING_MODE_CLEARTYPE_GDI_NATURAL,
-
- /// <summary>
- /// 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).
- /// </summary>
- DWRITE_RENDERING_MODE_CLEARTYPE_NATURAL,
-
- /// <summary>
- /// 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.
- /// </summary>
- DWRITE_RENDERING_MODE_CLEARTYPE_NATURAL_SYMMETRIC,
-
- /// <summary>
- /// Specifies that rendering should bypass the rasterizer and use the outlines directly. This is
- /// typically used at very large sizes.
- /// </summary>
- DWRITE_RENDERING_MODE_OUTLINE
-};
-
-/// <summary>
-/// The DWRITE_MATRIX structure specifies the graphics transform to be applied
-/// to rendered glyphs.
-/// </summary>
-struct DWRITE_MATRIX
-{
- /// <summary>
- /// Horizontal scaling / cosine of rotation
- /// </summary>
- FLOAT m11;
-
- /// <summary>
- /// Vertical shear / sine of rotation
- /// </summary>
- FLOAT m12;
-
- /// <summary>
- /// Horizontal shear / negative sine of rotation
- /// </summary>
- FLOAT m21;
-
- /// <summary>
- /// Vertical scaling / cosine of rotation
- /// </summary>
- FLOAT m22;
-
- /// <summary>
- /// Horizontal shift (always orthogonal regardless of rotation)
- /// </summary>
- FLOAT dx;
-
- /// <summary>
- /// Vertical shift (always orthogonal regardless of rotation)
- /// </summary>
- FLOAT dy;
-};
-
-/// <summary>
-/// The interface that represents text rendering settings for glyph rasterization and filtering.
-/// </summary>
-interface DWRITE_DECLARE_INTERFACE("2f0da53a-2add-47cd-82ee-d9ec34688e75") IDWriteRenderingParams : public IUnknown
-{
- /// <summary>
- /// Gets the gamma value used for gamma correction. Valid values must be
- /// greater than zero and cannot exceed 256.
- /// </summary>
- STDMETHOD_(FLOAT, GetGamma)() PURE;
-
- /// <summary>
- /// Gets the amount of contrast enhancement. Valid values are greater than
- /// or equal to zero.
- /// </summary>
- STDMETHOD_(FLOAT, GetEnhancedContrast)() PURE;
-
- /// <summary>
- /// Gets the ClearType level. Valid values range from 0.0f (no ClearType)
- /// to 1.0f (full ClearType).
- /// </summary>
- STDMETHOD_(FLOAT, GetClearTypeLevel)() PURE;
-
- /// <summary>
- /// Gets the pixel geometry.
- /// </summary>
- STDMETHOD_(DWRITE_PIXEL_GEOMETRY, GetPixelGeometry)() PURE;
-
- /// <summary>
- /// Gets the rendering mode.
- /// </summary>
- STDMETHOD_(DWRITE_RENDERING_MODE, GetRenderingMode)() PURE;
-};
-
-// Forward declarations of D2D types
-interface ID2D1SimplifiedGeometrySink;
-
-typedef ID2D1SimplifiedGeometrySink IDWriteGeometrySink;
-
-/// <summary>
-/// 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.
-/// </summary>
-interface DWRITE_DECLARE_INTERFACE("5f49804d-7024-4d43-bfa9-d25984f53849") IDWriteFontFace : public IUnknown
-{
- /// <summary>
- /// Obtains the file format type of a font face.
- /// </summary>
- STDMETHOD_(DWRITE_FONT_FACE_TYPE, GetType)() PURE;
-
- /// <summary>
- /// Obtains the font files representing a font face.
- /// </summary>
- /// <param name="numberOfFiles">The number of files representing the font face.</param>
- /// <param name="fontFiles">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.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetFiles)(
- __inout UINT32* numberOfFiles,
- __out_ecount_opt(*numberOfFiles) IDWriteFontFile** fontFiles
- ) PURE;
-
- /// <summary>
- /// 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.
- /// </summary>
- STDMETHOD_(UINT32, GetIndex)() PURE;
-
- /// <summary>
- /// Obtains the algorithmic style simulation flags of a font face.
- /// </summary>
- STDMETHOD_(DWRITE_FONT_SIMULATIONS, GetSimulations)() PURE;
-
- /// <summary>
- /// Determines whether the font is a symbol font.
- /// </summary>
- STDMETHOD_(BOOL, IsSymbolFont)() PURE;
-
- /// <summary>
- /// 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.
- /// </summary>
- /// <param name="fontFaceMetrics">Points to a DWRITE_FONT_METRICS structure to fill in.
- /// The metrics returned by this function are in font design units.</param>
- STDMETHOD_(void, GetMetrics)(
- __out DWRITE_FONT_METRICS* fontFaceMetrics
- ) PURE;
-
- /// <summary>
- /// Obtains the number of glyphs in the font face.
- /// </summary>
- STDMETHOD_(UINT16, GetGlyphCount)() PURE;
-
- /// <summary>
- /// Obtains ideal glyph metrics in font design units. Design glyphs metrics are used for glyph positioning.
- /// </summary>
- /// <param name="glyphIndices">An array of glyph indices to compute the metrics for.</param>
- /// <param name="glyphCount">The number of elements in the glyphIndices array.</param>
- /// <param name="glyphMetrics">Array of DWRITE_GLYPH_METRICS structures filled by this function.
- /// The metrics returned by this function are in font design units.</param>
- /// <param name="isSideways">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.</param>
- /// <returns>
- /// 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.
- /// </returns>
- STDMETHOD(GetDesignGlyphMetrics)(
- __in_ecount(glyphCount) UINT16 const* glyphIndices,
- UINT32 glyphCount,
- __out_ecount(glyphCount) DWRITE_GLYPH_METRICS* glyphMetrics,
- BOOL isSideways = FALSE
- ) PURE;
-
- /// <summary>
- /// 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.
- /// </summary>
- /// <param name="codePoints">An array of USC4 code points to obtain nominal glyph indices from.</param>
- /// <param name="codePointCount">The number of elements in the codePoints array.</param>
- /// <param name="glyphIndices">Array of nominal glyph indices filled by this function.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetGlyphIndices)(
- __in_ecount(codePointCount) UINT32 const* codePoints,
- UINT32 codePointCount,
- __out_ecount(codePointCount) UINT16* glyphIndices
- ) PURE;
-
- /// <summary>
- /// 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.
- /// </summary>
- /// <param name="openTypeTableTag">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.</param>
- /// <param name="tableData">
- /// 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).
- /// </param>
- /// <param name="tableSize">Byte size of table.</param>
- /// <param name="tableContext">
- /// 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.
- /// </param>
- /// <param name="exists">True if table exists.</param>
- /// <returns>
- /// 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.
- /// </returns>
- /// <remarks>
- /// The context for the same tag may be different for each call,
- /// so each one must be held and released separately.
- /// </remarks>
- STDMETHOD(TryGetFontTable)(
- __in UINT32 openTypeTableTag,
- __deref_out_bcount(*tableSize) const void** tableData,
- __out UINT32* tableSize,
- __out void** tableContext,
- __out BOOL* exists
- ) PURE;
-
- /// <summary>
- /// Releases the table obtained earlier from TryGetFontTable.
- /// </summary>
- /// <param name="tableContext">Opaque context from TryGetFontTable.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD_(void, ReleaseFontTable)(
- __in void* tableContext
- ) PURE;
-
- /// <summary>
- /// Computes the outline of a run of glyphs by calling back to the outline sink interface.
- /// </summary>
- /// <param name="emSize">Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.</param>
- /// <param name="glyphIndices">Array of glyph indices.</param>
- /// <param name="glyphAdvances">Optional array of glyph advances in DIPs.</param>
- /// <param name="glyphOffsets">Optional array of glyph offsets.</param>
- /// <param name="glyphCount">Number of glyphs.</param>
- /// <param name="isSideways">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.</param>
- /// <param name="isRightToLeft">If true, specifies that the advance direction is right to left. By default, the advance direction
- /// is left to right.</param>
- /// <param name="geometrySink">Interface the function calls back to draw each element of the geometry.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- 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;
-
- /// <summary>
- /// Determines the recommended rendering mode for the font given the specified size and rendering parameters.
- /// </summary>
- /// <param name="emSize">Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.</param>
- /// <param name="pixelsPerDip">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.</param>
- /// <param name="measuringMode">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
- /// </param>
- /// <param name="renderingParams">Rendering parameters object. This parameter is necessary in case the rendering parameters
- /// object overrides the rendering mode.</param>
- /// <param name="renderingMode">Receives the recommended rendering mode to use.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetRecommendedRenderingMode)(
- FLOAT emSize,
- FLOAT pixelsPerDip,
- DWRITE_MEASURING_MODE measuringMode,
- IDWriteRenderingParams* renderingParams,
- __out DWRITE_RENDERING_MODE* renderingMode
- ) PURE;
-
- /// <summary>
- /// 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.
- /// </summary>
- /// <param name="emSize">Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.</param>
- /// <param name="pixelsPerDip">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.</param>
- /// <param name="transform">Optional transform applied to the glyphs and their positions. This transform is applied after the
- /// scaling specified by the font size and pixelsPerDip.</param>
- /// <param name="fontFaceMetrics">Points to a DWRITE_FONT_METRICS structure to fill in.
- /// The metrics returned by this function are in font design units.</param>
- STDMETHOD(GetGdiCompatibleMetrics)(
- FLOAT emSize,
- FLOAT pixelsPerDip,
- __in_opt DWRITE_MATRIX const* transform,
- __out DWRITE_FONT_METRICS* fontFaceMetrics
- ) PURE;
-
-
- /// <summary>
- /// 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.
- /// </summary>
- /// <param name="emSize">Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.</param>
- /// <param name="pixelsPerDip">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.</param>
- /// <param name="transform">Optional transform applied to the glyphs and their positions. This transform is applied after the
- /// scaling specified by the font size and pixelsPerDip.</param>
- /// <param name="useGdiNatural">
- /// 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.
- /// </param>
- /// <param name="glyphIndices">An array of glyph indices to compute the metrics for.</param>
- /// <param name="glyphCount">The number of elements in the glyphIndices array.</param>
- /// <param name="glyphMetrics">Array of DWRITE_GLYPH_METRICS structures filled by this function.
- /// The metrics returned by this function are in font design units.</param>
- /// <param name="isSideways">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.</param>
- /// <returns>
- /// 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.
- /// </returns>
- 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;
-
-/// <summary>
-/// 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.
-/// </summary>
-interface DWRITE_DECLARE_INTERFACE("cca920e4-52f0-492b-bfa8-29c72ee0a468") IDWriteFontCollectionLoader : public IUnknown
-{
- /// <summary>
- /// 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.
- /// </summary>
- /// <param name="factory">Factory associated with the loader.</param>
- /// <param name="collectionKey">Font collection key that uniquely identifies the collection of font files within
- /// the scope of the font collection loader being used.</param>
- /// <param name="collectionKeySize">Size of the font collection key in bytes.</param>
- /// <param name="fontFileEnumerator">Pointer to the newly created font file enumerator.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(CreateEnumeratorFromKey)(
- IDWriteFactory* factory,
- __in_bcount(collectionKeySize) void const* collectionKey,
- UINT32 collectionKeySize,
- __out IDWriteFontFileEnumerator** fontFileEnumerator
- ) PURE;
-};
-
-/// <summary>
-/// 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.
-/// </summary>
-interface DWRITE_DECLARE_INTERFACE("72755049-5ff7-435d-8348-4be97cfa6c7c") IDWriteFontFileEnumerator : public IUnknown
-{
- /// <summary>
- /// 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.
- /// </summary>
- /// <param name="hasCurrentFile">Receives the value TRUE if the enumerator advances to a file, or FALSE if
- /// the enumerator advanced past the last file in the collection.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(MoveNext)(
- __out BOOL* hasCurrentFile
- ) PURE;
-
- /// <summary>
- /// Gets a reference to the current font file.
- /// </summary>
- /// <param name="fontFile">Pointer to the newly created font file object.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetCurrentFontFile)(
- __out IDWriteFontFile** fontFile
- ) PURE;
-};
-
-/// <summary>
-/// Represents a collection of strings indexed by locale name.
-/// </summary>
-interface DWRITE_DECLARE_INTERFACE("08256209-099a-4b34-b86d-c22b110e7771") IDWriteLocalizedStrings : public IUnknown
-{
- /// <summary>
- /// Gets the number of language/string pairs.
- /// </summary>
- STDMETHOD_(UINT32, GetCount)() PURE;
-
- /// <summary>
- /// Gets the index of the item with the specified locale name.
- /// </summary>
- /// <param name="localeName">Locale name to look for.</param>
- /// <param name="index">Receives the zero-based index of the locale name/string pair.</param>
- /// <param name="exists">Receives TRUE if the locale name exists or FALSE if not.</param>
- /// <returns>
- /// 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.
- /// </returns>
- STDMETHOD(FindLocaleName)(
- __in_z WCHAR const* localeName,
- __out UINT32* index,
- __out BOOL* exists
- ) PURE;
-
- /// <summary>
- /// Gets the length in characters (not including the null terminator) of the locale name with the specified index.
- /// </summary>
- /// <param name="index">Zero-based index of the locale name.</param>
- /// <param name="length">Receives the length in characters, not including the null terminator.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetLocaleNameLength)(
- UINT32 index,
- __out UINT32* length
- ) PURE;
-
- /// <summary>
- /// Copies the locale name with the specified index to the specified array.
- /// </summary>
- /// <param name="index">Zero-based index of the locale name.</param>
- /// <param name="localeName">Character array that receives the locale name.</param>
- /// <param name="size">Size of the array in characters. The size must include space for the terminating
- /// null character.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetLocaleName)(
- UINT32 index,
- __out_ecount_z(size) WCHAR* localeName,
- UINT32 size
- ) PURE;
-
- /// <summary>
- /// Gets the length in characters (not including the null terminator) of the string with the specified index.
- /// </summary>
- /// <param name="index">Zero-based index of the string.</param>
- /// <param name="length">Receives the length in characters, not including the null terminator.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetStringLength)(
- UINT32 index,
- __out UINT32* length
- ) PURE;
-
- /// <summary>
- /// Copies the string with the specified index to the specified array.
- /// </summary>
- /// <param name="index">Zero-based index of the string.</param>
- /// <param name="stringBuffer">Character array that receives the string.</param>
- /// <param name="size">Size of the array in characters. The size must include space for the terminating
- /// null character.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetString)(
- UINT32 index,
- __out_ecount_z(size) WCHAR* stringBuffer,
- UINT32 size
- ) PURE;
-};
-
-interface IDWriteFontFamily;
-interface IDWriteFont;
-
-/// <summary>
-/// The IDWriteFontCollection encapsulates a collection of fonts.
-/// </summary>
-interface DWRITE_DECLARE_INTERFACE("a84cee02-3eea-4eee-a827-87c1a02a0fcc") IDWriteFontCollection : public IUnknown
-{
- /// <summary>
- /// Gets the number of font families in the collection.
- /// </summary>
- STDMETHOD_(UINT32, GetFontFamilyCount)() PURE;
-
- /// <summary>
- /// Creates a font family object given a zero-based font family index.
- /// </summary>
- /// <param name="index">Zero-based index of the font family.</param>
- /// <param name="fontFamily">Receives a pointer the newly created font family object.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetFontFamily)(
- UINT32 index,
- __out IDWriteFontFamily** fontFamily
- ) PURE;
-
- /// <summary>
- /// Finds the font family with the specified family name.
- /// </summary>
- /// <param name="familyName">Name of the font family. The name is not case-sensitive but must otherwise exactly match a family name in the collection.</param>
- /// <param name="index">Receives the zero-based index of the matching font family if the family name was found or UINT_MAX otherwise.</param>
- /// <param name="exists">Receives TRUE if the family name exists or FALSE otherwise.</param>
- /// <returns>
- /// 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.
- /// </returns>
- STDMETHOD(FindFamilyName)(
- __in_z WCHAR const* familyName,
- __out UINT32* index,
- __out BOOL* exists
- ) PURE;
-
- /// <summary>
- /// 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.
- /// </summary>
- /// <param name="fontFace">Font face object that specifies the physical font.</param>
- /// <param name="font">Receives a pointer to the newly created font object if successful or NULL otherwise.</param>
- /// <returns>
- /// Standard HRESULT error code. If the specified physical font is not part of the font collection the return value is DWRITE_E_NOFONT.
- /// </returns>
- STDMETHOD(GetFontFromFontFace)(
- IDWriteFontFace* fontFace,
- __out IDWriteFont** font
- ) PURE;
-};
-
-/// <summary>
-/// The IDWriteFontList interface represents a list of fonts.
-/// </summary>
-interface DWRITE_DECLARE_INTERFACE("1a0d8438-1d97-4ec1-aef9-a2fb86ed6acb") IDWriteFontList : public IUnknown
-{
- /// <summary>
- /// Gets the font collection that contains the fonts.
- /// </summary>
- /// <param name="fontCollection">Receives a pointer to the font collection object.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetFontCollection)(
- __out IDWriteFontCollection** fontCollection
- ) PURE;
-
- /// <summary>
- /// Gets the number of fonts in the font list.
- /// </summary>
- STDMETHOD_(UINT32, GetFontCount)() PURE;
-
- /// <summary>
- /// Gets a font given its zero-based index.
- /// </summary>
- /// <param name="index">Zero-based index of the font in the font list.</param>
- /// <param name="font">Receives a pointer to the newly created font object.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetFont)(
- UINT32 index,
- __out IDWriteFont** font
- ) PURE;
-};
-
-/// <summary>
-/// The IDWriteFontFamily interface represents a set of fonts that share the same design but are differentiated
-/// by weight, stretch, and style.
-/// </summary>
-interface DWRITE_DECLARE_INTERFACE("da20d8ef-812a-4c43-9802-62ec4abd7add") IDWriteFontFamily : public IDWriteFontList
-{
- /// <summary>
- /// Creates an localized strings object that contains the family names for the font family, indexed by locale name.
- /// </summary>
- /// <param name="names">Receives a pointer to the newly created localized strings object.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetFamilyNames)(
- __out IDWriteLocalizedStrings** names
- ) PURE;
-
- /// <summary>
- /// Gets the font that best matches the specified properties.
- /// </summary>
- /// <param name="weight">Requested font weight.</param>
- /// <param name="stretch">Requested font stretch.</param>
- /// <param name="style">Requested font style.</param>
- /// <param name="matchingFont">Receives a pointer to the newly created font object.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetFirstMatchingFont)(
- DWRITE_FONT_WEIGHT weight,
- DWRITE_FONT_STRETCH stretch,
- DWRITE_FONT_STYLE style,
- __out IDWriteFont** matchingFont
- ) PURE;
-
- /// <summary>
- /// Gets a list of fonts in the font family ranked in order of how well they match the specified properties.
- /// </summary>
- /// <param name="weight">Requested font weight.</param>
- /// <param name="stretch">Requested font stretch.</param>
- /// <param name="style">Requested font style.</param>
- /// <param name="matchingFonts">Receives a pointer to the newly created font list object.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetMatchingFonts)(
- DWRITE_FONT_WEIGHT weight,
- DWRITE_FONT_STRETCH stretch,
- DWRITE_FONT_STYLE style,
- __out IDWriteFontList** matchingFonts
- ) PURE;
-};
-
-/// <summary>
-/// The IDWriteFont interface represents a physical font in a font collection.
-/// </summary>
-interface DWRITE_DECLARE_INTERFACE("acd16696-8c14-4f5d-877e-fe3fc1d32737") IDWriteFont : public IUnknown
-{
- /// <summary>
- /// Gets the font family to which the specified font belongs.
- /// </summary>
- /// <param name="fontFamily">Receives a pointer to the font family object.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetFontFamily)(
- __out IDWriteFontFamily** fontFamily
- ) PURE;
-
- /// <summary>
- /// Gets the weight of the specified font.
- /// </summary>
- STDMETHOD_(DWRITE_FONT_WEIGHT, GetWeight)() PURE;
-
- /// <summary>
- /// Gets the stretch (aka. width) of the specified font.
- /// </summary>
- STDMETHOD_(DWRITE_FONT_STRETCH, GetStretch)() PURE;
-
- /// <summary>
- /// Gets the style (aka. slope) of the specified font.
- /// </summary>
- STDMETHOD_(DWRITE_FONT_STYLE, GetStyle)() PURE;
-
- /// <summary>
- /// Returns TRUE if the font is a symbol font or FALSE if not.
- /// </summary>
- STDMETHOD_(BOOL, IsSymbolFont)() PURE;
-
- /// <summary>
- /// Gets a localized strings collection containing the face names for the font (e.g., Regular or Bold), indexed by locale name.
- /// </summary>
- /// <param name="names">Receives a pointer to the newly created localized strings object.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetFaceNames)(
- __out IDWriteLocalizedStrings** names
- ) PURE;
-
- /// <summary>
- /// Gets a localized strings collection containing the specified informational strings, indexed by locale name.
- /// </summary>
- /// <param name="informationalStringID">Identifies the string to get.</param>
- /// <param name="informationalStrings">Receives a pointer to the newly created localized strings object.</param>
- /// <param name="exists">Receives the value TRUE if the font contains the specified string ID or FALSE if not.</param>
- /// <returns>
- /// 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.
- /// </returns>
- STDMETHOD(GetInformationalStrings)(
- DWRITE_INFORMATIONAL_STRING_ID informationalStringID,
- __out IDWriteLocalizedStrings** informationalStrings,
- __out BOOL* exists
- ) PURE;
-
- /// <summary>
- /// Gets a value that indicates what simulation are applied to the specified font.
- /// </summary>
- STDMETHOD_(DWRITE_FONT_SIMULATIONS, GetSimulations)() PURE;
-
- /// <summary>
- /// Gets the metrics for the font.
- /// </summary>
- /// <param name="fontMetrics">Receives the font metrics.</param>
- STDMETHOD_(void, GetMetrics)(
- __out DWRITE_FONT_METRICS* fontMetrics
- ) PURE;
-
- /// <summary>
- /// Determines whether the font supports the specified character.
- /// </summary>
- /// <param name="unicodeValue">Unicode (UCS-4) character value.</param>
- /// <param name="exists">Receives the value TRUE if the font supports the specified character or FALSE if not.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(HasCharacter)(
- UINT32 unicodeValue,
- __out BOOL* exists
- ) PURE;
-
- /// <summary>
- /// Creates a font face object for the font.
- /// </summary>
- /// <param name="fontFace">Receives a pointer to the newly created font face object.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(CreateFontFace)(
- __out IDWriteFontFace** fontFace
- ) PURE;
-};
-
-/// <summary>
-/// Direction for how reading progresses.
-/// </summary>
-enum DWRITE_READING_DIRECTION
-{
- /// <summary>
- /// Reading progresses from left to right.
- /// </summary>
- DWRITE_READING_DIRECTION_LEFT_TO_RIGHT,
-
- /// <summary>
- /// Reading progresses from right to left.
- /// </summary>
- DWRITE_READING_DIRECTION_RIGHT_TO_LEFT
-};
-
-/// <summary>
-/// Direction for how lines of text are placed relative to one another.
-/// </summary>
-enum DWRITE_FLOW_DIRECTION
-{
- /// <summary>
- /// Text lines are placed from top to bottom.
- /// </summary>
- DWRITE_FLOW_DIRECTION_TOP_TO_BOTTOM
-};
-
-/// <summary>
-/// Alignment of paragraph text along the reading direction axis relative to
-/// the leading and trailing edge of the layout box.
-/// </summary>
-enum DWRITE_TEXT_ALIGNMENT
-{
- /// <summary>
- /// The leading edge of the paragraph text is aligned to the layout box's leading edge.
- /// </summary>
- DWRITE_TEXT_ALIGNMENT_LEADING,
-
- /// <summary>
- /// The trailing edge of the paragraph text is aligned to the layout box's trailing edge.
- /// </summary>
- DWRITE_TEXT_ALIGNMENT_TRAILING,
-
- /// <summary>
- /// The center of the paragraph text is aligned to the center of the layout box.
- /// </summary>
- DWRITE_TEXT_ALIGNMENT_CENTER
-};
-
-/// <summary>
-/// Alignment of paragraph text along the flow direction axis relative to the
-/// flow's beginning and ending edge of the layout box.
-/// </summary>
-enum DWRITE_PARAGRAPH_ALIGNMENT
-{
- /// <summary>
- /// The first line of paragraph is aligned to the flow's beginning edge of the layout box.
- /// </summary>
- DWRITE_PARAGRAPH_ALIGNMENT_NEAR,
-
- /// <summary>
- /// The last line of paragraph is aligned to the flow's ending edge of the layout box.
- /// </summary>
- DWRITE_PARAGRAPH_ALIGNMENT_FAR,
-
- /// <summary>
- /// The center of the paragraph is aligned to the center of the flow of the layout box.
- /// </summary>
- DWRITE_PARAGRAPH_ALIGNMENT_CENTER
-};
-
-/// <summary>
-/// Word wrapping in multiline paragraph.
-/// </summary>
-enum DWRITE_WORD_WRAPPING
-{
- /// <summary>
- /// Words are broken across lines to avoid text overflowing the layout box.
- /// </summary>
- DWRITE_WORD_WRAPPING_WRAP,
-
- /// <summary>
- /// 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.
- /// </summary>
- DWRITE_WORD_WRAPPING_NO_WRAP
-};
-
-/// <summary>
-/// The method used for line spacing in layout.
-/// </summary>
-enum DWRITE_LINE_SPACING_METHOD
-{
- /// <summary>
- /// Line spacing depends solely on the content, growing to accomodate the size of fonts and inline objects.
- /// </summary>
- DWRITE_LINE_SPACING_METHOD_DEFAULT,
-
- /// <summary>
- /// 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.
- /// </summary>
- DWRITE_LINE_SPACING_METHOD_UNIFORM
-};
-
-/// <summary>
-/// Text granularity used to trim text overflowing the layout box.
-/// </summary>
-enum DWRITE_TRIMMING_GRANULARITY
-{
- /// <summary>
- /// No trimming occurs. Text flows beyond the layout width.
- /// </summary>
- DWRITE_TRIMMING_GRANULARITY_NONE,
-
- /// <summary>
- /// Trimming occurs at character cluster boundary.
- /// </summary>
- DWRITE_TRIMMING_GRANULARITY_CHARACTER,
-
- /// <summary>
- /// Trimming occurs at word boundary.
- /// </summary>
- DWRITE_TRIMMING_GRANULARITY_WORD
-};
-
-/// <summary>
-/// Typographic feature of text supplied by the font.
-/// </summary>
-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'
-};
-
-/// <summary>
-/// The DWRITE_TEXT_RANGE structure specifies a range of text positions where format is applied.
-/// </summary>
-struct DWRITE_TEXT_RANGE
-{
- /// <summary>
- /// The start text position of the range.
- /// </summary>
- UINT32 startPosition;
-
- /// <summary>
- /// The number of text positions in the range.
- /// </summary>
- UINT32 length;
-};
-
-/// <summary>
-/// The DWRITE_FONT_FEATURE structure specifies properties used to identify and execute typographic feature in the font.
-/// </summary>
-struct DWRITE_FONT_FEATURE
-{
- /// <summary>
- /// The feature OpenType name identifier.
- /// </summary>
- DWRITE_FONT_FEATURE_TAG nameTag;
-
- /// <summary>
- /// Execution parameter of the feature.
- /// </summary>
- /// <remarks>
- /// 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.
- /// </remarks>
- UINT32 parameter;
-};
-
-/// <summary>
-/// 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.
-/// </summary>
-struct DWRITE_TYPOGRAPHIC_FEATURES
-{
- /// <summary>
- /// Array of font features.
- /// </summary>
- __field_ecount(featureCount) DWRITE_FONT_FEATURE* features;
-
- /// <summary>
- /// The number of features.
- /// </summary>
- UINT32 featureCount;
-};
-
-/// <summary>
-/// The DWRITE_TRIMMING structure specifies the trimming option for text overflowing the layout box.
-/// </summary>
-struct DWRITE_TRIMMING
-{
- /// <summary>
- /// Text granularity of which trimming applies.
- /// </summary>
- DWRITE_TRIMMING_GRANULARITY granularity;
-
- /// <summary>
- /// 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.
- /// </summary>
- UINT32 delimiter;
-
- /// <summary>
- /// How many occurences of the delimiter to step back.
- /// </summary>
- UINT32 delimiterCount;
-};
-
-
-interface IDWriteTypography;
-interface IDWriteInlineObject;
-
-/// <summary>
-/// The format of text used for text layout purpose.
-/// </summary>
-/// <remarks>
-/// This object may not be thread-safe and it may carry the state of text format change.
-/// </remarks>
-interface DWRITE_DECLARE_INTERFACE("9c906818-31d7-4fd3-a151-7c5e225db55a") IDWriteTextFormat : public IUnknown
-{
- /// <summary>
- /// Set alignment option of text relative to layout box's leading and trailing edge.
- /// </summary>
- /// <param name="textAlignment">Text alignment option</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(SetTextAlignment)(
- DWRITE_TEXT_ALIGNMENT textAlignment
- ) PURE;
-
- /// <summary>
- /// Set alignment option of paragraph relative to layout box's top and bottom edge.
- /// </summary>
- /// <param name="paragraphAlignment">Paragraph alignment option</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(SetParagraphAlignment)(
- DWRITE_PARAGRAPH_ALIGNMENT paragraphAlignment
- ) PURE;
-
- /// <summary>
- /// Set word wrapping option.
- /// </summary>
- /// <param name="wordWrapping">Word wrapping option</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(SetWordWrapping)(
- DWRITE_WORD_WRAPPING wordWrapping
- ) PURE;
-
- /// <summary>
- /// Set paragraph reading direction.
- /// </summary>
- /// <param name="readingDirection">Text reading direction</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(SetReadingDirection)(
- DWRITE_READING_DIRECTION readingDirection
- ) PURE;
-
- /// <summary>
- /// Set paragraph flow direction.
- /// </summary>
- /// <param name="flowDirection">Paragraph flow direction</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(SetFlowDirection)(
- DWRITE_FLOW_DIRECTION flowDirection
- ) PURE;
-
- /// <summary>
- /// Set incremental tab stop position.
- /// </summary>
- /// <param name="incrementalTabStop">The incremental tab stop value</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(SetIncrementalTabStop)(
- FLOAT incrementalTabStop
- ) PURE;
-
- /// <summary>
- /// Set trimming options for any trailing text exceeding the layout width
- /// or for any far text exceeding the layout height.
- /// </summary>
- /// <param name="trimmingOptions">Text trimming options.</param>
- /// <param name="trimmingSign">Application-defined omission sign. This parameter may be NULL if no trimming sign is desired.</param>
- /// <remarks>
- /// 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.
- /// </remarks>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(SetTrimming)(
- __in DWRITE_TRIMMING const* trimmingOptions,
- IDWriteInlineObject* trimmingSign
- ) PURE;
-
- /// <summary>
- /// Set line spacing.
- /// </summary>
- /// <param name="lineSpacingMethod">How to determine line height.</param>
- /// <param name="lineSpacing">The line height, or rather distance between one baseline to another.</param>
- /// <param name="baseline">Distance from top of line to baseline. A reasonable ratio to lineSpacing is 80%.</param>
- /// <remarks>
- /// For the default method, spacing depends solely on the content.
- /// For uniform spacing, the given line height will override the content.
- /// </remarks>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(SetLineSpacing)(
- DWRITE_LINE_SPACING_METHOD lineSpacingMethod,
- FLOAT lineSpacing,
- FLOAT baseline
- ) PURE;
-
- /// <summary>
- /// Get alignment option of text relative to layout box's leading and trailing edge.
- /// </summary>
- STDMETHOD_(DWRITE_TEXT_ALIGNMENT, GetTextAlignment)() PURE;
-
- /// <summary>
- /// Get alignment option of paragraph relative to layout box's top and bottom edge.
- /// </summary>
- STDMETHOD_(DWRITE_PARAGRAPH_ALIGNMENT, GetParagraphAlignment)() PURE;
-
- /// <summary>
- /// Get word wrapping option.
- /// </summary>
- STDMETHOD_(DWRITE_WORD_WRAPPING, GetWordWrapping)() PURE;
-
- /// <summary>
- /// Get paragraph reading direction.
- /// </summary>
- STDMETHOD_(DWRITE_READING_DIRECTION, GetReadingDirection)() PURE;
-
- /// <summary>
- /// Get paragraph flow direction.
- /// </summary>
- STDMETHOD_(DWRITE_FLOW_DIRECTION, GetFlowDirection)() PURE;
-
- /// <summary>
- /// Get incremental tab stop position.
- /// </summary>
- STDMETHOD_(FLOAT, GetIncrementalTabStop)() PURE;
-
- /// <summary>
- /// Get trimming options for text overflowing the layout width.
- /// </summary>
- /// <param name="trimmingOptions">Text trimming options.</param>
- /// <param name="trimmingSign">Trimming omission sign. This parameter may be NULL.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetTrimming)(
- __out DWRITE_TRIMMING* trimmingOptions,
- __out IDWriteInlineObject** trimmingSign
- ) PURE;
-
- /// <summary>
- /// Get line spacing.
- /// </summary>
- /// <param name="lineSpacingMethod">How line height is determined.</param>
- /// <param name="lineSpacing">The line height, or rather distance between one baseline to another.</param>
- /// <param name="baseline">Distance from top of line to baseline.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetLineSpacing)(
- __out DWRITE_LINE_SPACING_METHOD* lineSpacingMethod,
- __out FLOAT* lineSpacing,
- __out FLOAT* baseline
- ) PURE;
-
- /// <summary>
- /// Get the font collection.
- /// </summary>
- /// <param name="fontCollection">The current font collection.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetFontCollection)(
- __out IDWriteFontCollection** fontCollection
- ) PURE;
-
- /// <summary>
- /// Get the length of the font family name, in characters, not including the terminating NULL character.
- /// </summary>
- STDMETHOD_(UINT32, GetFontFamilyNameLength)() PURE;
-
- /// <summary>
- /// Get a copy of the font family name.
- /// </summary>
- /// <param name="fontFamilyName">Character array that receives the current font family name</param>
- /// <param name="nameSize">Size of the character array in character count including the terminated NULL character.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetFontFamilyName)(
- __out_ecount_z(nameSize) WCHAR* fontFamilyName,
- UINT32 nameSize
- ) PURE;
-
- /// <summary>
- /// Get the font weight.
- /// </summary>
- STDMETHOD_(DWRITE_FONT_WEIGHT, GetFontWeight)() PURE;
-
- /// <summary>
- /// Get the font style.
- /// </summary>
- STDMETHOD_(DWRITE_FONT_STYLE, GetFontStyle)() PURE;
-
- /// <summary>
- /// Get the font stretch.
- /// </summary>
- STDMETHOD_(DWRITE_FONT_STRETCH, GetFontStretch)() PURE;
-
- /// <summary>
- /// Get the font em height.
- /// </summary>
- STDMETHOD_(FLOAT, GetFontSize)() PURE;
-
- /// <summary>
- /// Get the length of the locale name, in characters, not including the terminating NULL character.
- /// </summary>
- STDMETHOD_(UINT32, GetLocaleNameLength)() PURE;
-
- /// <summary>
- /// Get a copy of the locale name.
- /// </summary>
- /// <param name="localeName">Character array that receives the current locale name</param>
- /// <param name="nameSize">Size of the character array in character count including the terminated NULL character.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetLocaleName)(
- __out_ecount_z(nameSize) WCHAR* localeName,
- UINT32 nameSize
- ) PURE;
-};
-
-
-/// <summary>
-/// Font typography setting.
-/// </summary>
-interface DWRITE_DECLARE_INTERFACE("55f1112b-1dc2-4b3c-9541-f46894ed85b6") IDWriteTypography : public IUnknown
-{
- /// <summary>
- /// Add font feature.
- /// </summary>
- /// <param name="fontFeature">The font feature to add.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(AddFontFeature)(
- DWRITE_FONT_FEATURE fontFeature
- ) PURE;
-
- /// <summary>
- /// Get the number of font features.
- /// </summary>
- STDMETHOD_(UINT32, GetFontFeatureCount)() PURE;
-
- /// <summary>
- /// Get the font feature at the specified index.
- /// </summary>
- /// <param name="fontFeatureIndex">The zero-based index of the font feature to get.</param>
- /// <param name="fontFeature">The font feature.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetFontFeature)(
- UINT32 fontFeatureIndex,
- __out DWRITE_FONT_FEATURE* fontFeature
- ) PURE;
-};
-
-enum DWRITE_SCRIPT_SHAPES
-{
- /// <summary>
- /// No additional shaping requirement. Text is shaped with the writing system default behavior.
- /// </summary>
- DWRITE_SCRIPT_SHAPES_DEFAULT = 0,
-
- /// <summary>
- /// Text should leave no visual on display i.e. control or format control characters.
- /// </summary>
- DWRITE_SCRIPT_SHAPES_NO_VISUAL = 1
-};
-
-#ifdef DEFINE_ENUM_FLAG_OPERATORS
-DEFINE_ENUM_FLAG_OPERATORS(DWRITE_SCRIPT_SHAPES);
-#endif
-
-/// <summary>
-/// Association of text and its writing system script as well as some display attributes.
-/// </summary>
-struct DWRITE_SCRIPT_ANALYSIS
-{
- /// <summary>
- /// Zero-based index representation of writing system script.
- /// </summary>
- UINT16 script;
-
- /// <summary>
- /// Additional shaping requirement of text.
- /// </summary>
- DWRITE_SCRIPT_SHAPES shapes;
-};
-
-/// <summary>
-/// Condition at the edges of inline object or text used to determine
-/// line-breaking behavior.
-/// </summary>
-enum DWRITE_BREAK_CONDITION
-{
- /// <summary>
- /// Whether a break is allowed is determined by the condition of the
- /// neighboring text span or inline object.
- /// </summary>
- DWRITE_BREAK_CONDITION_NEUTRAL,
-
- /// <summary>
- /// 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.
- /// </summary>
- DWRITE_BREAK_CONDITION_CAN_BREAK,
-
- /// <summary>
- /// There should be no break, unless overruled by a Must condition from
- /// the neighboring text span or inline object.
- /// </summary>
- DWRITE_BREAK_CONDITION_MAY_NOT_BREAK,
-
- /// <summary>
- /// The break must happen, regardless of the condition of the adjacent
- /// text span or inline object.
- /// </summary>
- DWRITE_BREAK_CONDITION_MUST_BREAK
-};
-
-/// <summary>
-/// Line breakpoint characteristics of a character.
-/// </summary>
-struct DWRITE_LINE_BREAKPOINT
-{
- /// <summary>
- /// Breaking condition before the character.
- /// </summary>
- UINT8 breakConditionBefore : 2;
-
- /// <summary>
- /// Breaking condition after the character.
- /// </summary>
- UINT8 breakConditionAfter : 2;
-
- /// <summary>
- /// The character is some form of whitespace, which may be meaningful
- /// for justification.
- /// </summary>
- UINT8 isWhitespace : 1;
-
- /// <summary>
- /// The character is a soft hyphen, often used to indicate hyphenation
- /// points inside words.
- /// </summary>
- UINT8 isSoftHyphen : 1;
-
- UINT8 padding : 2;
-};
-
-/// <summary>
-/// How to apply number substitution on digits and related punctuation.
-/// </summary>
-enum DWRITE_NUMBER_SUBSTITUTION_METHOD
-{
- /// <summary>
- /// Specifies that the substitution method should be determined based
- /// on LOCALE_IDIGITSUBSTITUTION value of the specified text culture.
- /// </summary>
- DWRITE_NUMBER_SUBSTITUTION_METHOD_FROM_CULTURE,
-
- /// <summary>
- /// 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.
- /// </summary>
- DWRITE_NUMBER_SUBSTITUTION_METHOD_CONTEXTUAL,
-
- /// <summary>
- /// Specifies that code points 0x30-0x39 are always rendered as nominal numeral
- /// shapes (ones of the European number), i.e., no substitution is performed.
- /// </summary>
- DWRITE_NUMBER_SUBSTITUTION_METHOD_NONE,
-
- /// <summary>
- /// Specifies that number are rendered using the national number shape
- /// as specified by the LOCALE_SNATIVEDIGITS value of the specified text culture.
- /// </summary>
- DWRITE_NUMBER_SUBSTITUTION_METHOD_NATIONAL,
-
- /// <summary>
- /// 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.
- /// </summary>
- DWRITE_NUMBER_SUBSTITUTION_METHOD_TRADITIONAL
-};
-
-/// <summary>
-/// Holds the appropriate digits and numeric punctuation for a given locale.
-/// </summary>
-interface DECLSPEC_UUID("14885CC9-BAB0-4f90-B6ED-5C366A2CD03D") DECLSPEC_NOVTABLE IDWriteNumberSubstitution : public IUnknown
-{
-};
-
-/// <summary>
-/// Shaping output properties per input character.
-/// </summary>
-struct DWRITE_SHAPING_TEXT_PROPERTIES
-{
- /// <summary>
- /// This character can be shaped independently from the others
- /// (usually set for the space character).
- /// </summary>
- UINT16 isShapedAlone : 1;
-
- /// <summary>
- /// Reserved for use by shaping engine.
- /// </summary>
- UINT16 reserved : 15;
-};
-
-/// <summary>
-/// Shaping output properties per output glyph.
-/// </summary>
-struct DWRITE_SHAPING_GLYPH_PROPERTIES
-{
- /// <summary>
- /// Justification class, whether to use spacing, kashidas, or
- /// another method. This exists for backwards compatibility
- /// with Uniscribe's SCRIPT_JUSTIFY enum.
- /// </summary>
- UINT16 justification : 4;
-
- /// <summary>
- /// Indicates glyph is the first of a cluster.
- /// </summary>
- UINT16 isClusterStart : 1;
-
- /// <summary>
- /// Glyph is a diacritic.
- /// </summary>
- UINT16 isDiacritic : 1;
-
- /// <summary>
- /// Glyph has no width, blank, ZWJ, ZWNJ etc.
- /// </summary>
- UINT16 isZeroWidthSpace : 1;
-
- /// <summary>
- /// Reserved for use by shaping engine.
- /// </summary>
- UINT16 reserved : 9;
-};
-
-/// <summary>
-/// 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.
-/// </summary>
-interface DECLSPEC_UUID("688e1a58-5094-47c8-adc8-fbcea60ae92b") DECLSPEC_NOVTABLE IDWriteTextAnalysisSource : public IUnknown
-{
- /// <summary>
- /// 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.
- /// </summary>
- /// <param name="textPosition">First position of the piece to obtain. All
- /// positions are in UTF16 code-units, not whole characters, which
- /// matters when supplementary characters are used.</param>
- /// <param name="textString">Address that receives a pointer to the text block
- /// at the specified position.</param>
- /// <param name="textLength">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.</param>
- /// <returns>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.</returns>
- /// <remarks>
- /// 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.
- /// </remarks>
- STDMETHOD(GetTextAtPosition)(
- UINT32 textPosition,
- __out WCHAR const** textString,
- __out UINT32* textLength
- ) PURE;
-
- /// <summary>
- /// Get a block of text immediately preceding the specified position.
- /// </summary>
- /// <param name="textPosition">Position immediately after the last position of the chunk to obtain.</param>
- /// <param name="textString">Address that receives a pointer to the text block
- /// at the specified position.</param>
- /// <param name="textLength">Number of UTF16 units of the retrieved block.
- /// The length returned is from the given position to the front of
- /// the block.</param>
- /// <returns>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.</returns>
- /// <remarks>
- /// 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.
- /// </remarks>
- STDMETHOD(GetTextBeforePosition)(
- UINT32 textPosition,
- __out WCHAR const** textString,
- __out UINT32* textLength
- ) PURE;
-
- /// <summary>
- /// Get paragraph reading direction.
- /// </summary>
- STDMETHOD_(DWRITE_READING_DIRECTION, GetParagraphReadingDirection)() PURE;
-
- /// <summary>
- /// Get locale name on the range affected by it.
- /// </summary>
- /// <param name="textPosition">Position to get the locale name of.</param>
- /// <param name="textLength">Receives the length from the given position up to the
- /// next differing locale.</param>
- /// <param name="localeName">Address that receives a pointer to the locale
- /// at the specified position.</param>
- /// <remarks>
- /// The localeName pointer must remain valid until the next call or until
- /// the analysis returns.
- /// </remarks>
- STDMETHOD(GetLocaleName)(
- UINT32 textPosition,
- __out UINT32* textLength,
- __out_z WCHAR const** localeName
- ) PURE;
-
- /// <summary>
- /// Get number substitution on the range affected by it.
- /// </summary>
- /// <param name="textPosition">Position to get the number substitution of.</param>
- /// <param name="textLength">Receives the length from the given position up to the
- /// next differing number substitution.</param>
- /// <param name="numberSubstitution">Address that receives a pointer to the number substitution
- /// at the specified position.</param>
- /// <remarks>
- /// 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.
- /// </remarks>
- STDMETHOD(GetNumberSubstitution)(
- UINT32 textPosition,
- __out UINT32* textLength,
- __out IDWriteNumberSubstitution** numberSubstitution
- ) PURE;
-};
-
-/// <summary>
-/// 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.
-/// </summary>
-interface DECLSPEC_UUID("5810cd44-0ca0-4701-b3fa-bec5182ae4f6") DECLSPEC_NOVTABLE IDWriteTextAnalysisSink : public IUnknown
-{
- /// <summary>
- /// Report script analysis for the text range.
- /// </summary>
- /// <param name="textPosition">Starting position to report from.</param>
- /// <param name="textLength">Number of UTF16 units of the reported range.</param>
- /// <param name="scriptAnalysis">Script analysis of characters in range.</param>
- /// <returns>
- /// A successful code or error code to abort analysis.
- /// </returns>
- STDMETHOD(SetScriptAnalysis)(
- UINT32 textPosition,
- UINT32 textLength,
- __in DWRITE_SCRIPT_ANALYSIS const* scriptAnalysis
- ) PURE;
-
- /// <summary>
- /// Repport line-break opportunities for each character, starting from
- /// the specified position.
- /// </summary>
- /// <param name="textPosition">Starting position to report from.</param>
- /// <param name="textLength">Number of UTF16 units of the reported range.</param>
- /// <param name="lineBreakpoints">Breaking conditions for each character.</param>
- /// <returns>
- /// A successful code or error code to abort analysis.
- /// </returns>
- STDMETHOD(SetLineBreakpoints)(
- UINT32 textPosition,
- UINT32 textLength,
- __in_ecount(textLength) DWRITE_LINE_BREAKPOINT const* lineBreakpoints
- ) PURE;
-
- /// <summary>
- /// Set bidirectional level on the range, called once per each
- /// level run change (either explicit or resolved implicit).
- /// </summary>
- /// <param name="textPosition">Starting position to report from.</param>
- /// <param name="textLength">Number of UTF16 units of the reported range.</param>
- /// <param name="explicitLevel">Explicit level from embedded control codes
- /// RLE/RLO/LRE/LRO/PDF, determined before any additional rules.</param>
- /// <param name="resolvedLevel">Final implicit level considering the
- /// explicit level and characters' natural directionality, after all
- /// Bidi rules have been applied.</param>
- /// <returns>
- /// A successful code or error code to abort analysis.
- /// </returns>
- STDMETHOD(SetBidiLevel)(
- UINT32 textPosition,
- UINT32 textLength,
- UINT8 explicitLevel,
- UINT8 resolvedLevel
- ) PURE;
-
- /// <summary>
- /// Set number substitution on the range.
- /// </summary>
- /// <param name="textPosition">Starting position to report from.</param>
- /// <param name="textLength">Number of UTF16 units of the reported range.</param>
- /// <param name="numberSubstitution">The number substitution applicable to
- /// the returned range of text. The sink callback may hold onto it by
- /// incrementing its ref count.</param>
- /// <returns>
- /// A successful code or error code to abort analysis.
- /// </returns>
- /// <remark>
- /// 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.
- /// </remark>
- STDMETHOD(SetNumberSubstitution)(
- UINT32 textPosition,
- UINT32 textLength,
- __notnull IDWriteNumberSubstitution* numberSubstitution
- ) PURE;
-};
-
-/// <summary>
-/// Analyzes various text properties for complex script processing.
-/// </summary>
-interface DWRITE_DECLARE_INTERFACE("b7e6163e-7f46-43b4-84b3-e4e6249c365d") IDWriteTextAnalyzer : public IUnknown
-{
- /// <summary>
- /// Analyzes a text range for script boundaries, reading text attributes
- /// from the source and reporting the Unicode script ID to the sink
- /// callback SetScript.
- /// </summary>
- /// <param name="analysisSource">Source object to analyze.</param>
- /// <param name="textPosition">Starting position within the source object.</param>
- /// <param name="textLength">Length to analyze.</param>
- /// <param name="analysisSink">Callback object.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(AnalyzeScript)(
- IDWriteTextAnalysisSource* analysisSource,
- UINT32 textPosition,
- UINT32 textLength,
- IDWriteTextAnalysisSink* analysisSink
- ) PURE;
-
- /// <summary>
- /// Analyzes a text range for script directionality, reading attributes
- /// from the source and reporting levels to the sink callback SetBidiLevel.
- /// </summary>
- /// <param name="analysisSource">Source object to analyze.</param>
- /// <param name="textPosition">Starting position within the source object.</param>
- /// <param name="textLength">Length to analyze.</param>
- /// <param name="analysisSink">Callback object.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- /// <remarks>
- /// 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.
- /// </remarks>
- /// <remarks>
- /// Embedded control codes (LRE/LRO/RLE/RLO/PDF) are taken into account.
- /// </remarks>
- STDMETHOD(AnalyzeBidi)(
- IDWriteTextAnalysisSource* analysisSource,
- UINT32 textPosition,
- UINT32 textLength,
- IDWriteTextAnalysisSink* analysisSink
- ) PURE;
-
- /// <summary>
- /// 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.
- /// </summary>
- /// <param name="analysisSource">Source object to analyze.</param>
- /// <param name="textPosition">Starting position within the source object.</param>
- /// <param name="textLength">Length to analyze.</param>
- /// <param name="analysisSink">Callback object.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- /// <remarks>
- /// 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.
- /// </remarks>
- /// <remarks>
- /// Embedded control codes (LRE/LRO/RLE/RLO/PDF) are taken into account.
- /// </remarks>
- STDMETHOD(AnalyzeNumberSubstitution)(
- IDWriteTextAnalysisSource* analysisSource,
- UINT32 textPosition,
- UINT32 textLength,
- IDWriteTextAnalysisSink* analysisSink
- ) PURE;
-
- /// <summary>
- /// Analyzes a text range for potential breakpoint opportunities, reading
- /// attributes from the source and reporting breakpoint opportunities to
- /// the sink callback SetLineBreakpoints.
- /// </summary>
- /// <param name="analysisSource">Source object to analyze.</param>
- /// <param name="textPosition">Starting position within the source object.</param>
- /// <param name="textLength">Length to analyze.</param>
- /// <param name="analysisSink">Callback object.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- /// <remarks>
- /// 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.
- /// </remarks>
- /// <remarks>
- /// 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.
- /// </remarks>
- STDMETHOD(AnalyzeLineBreakpoints)(
- IDWriteTextAnalysisSource* analysisSource,
- UINT32 textPosition,
- UINT32 textLength,
- IDWriteTextAnalysisSink* analysisSink
- ) PURE;
-
- /// <summary>
- /// 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.
- /// </summary>
- /// <param name="textString">The string to convert to glyphs.</param>
- /// <param name="textLength">The length of textString.</param>
- /// <param name="fontFace">The font face to get glyphs from.</param>
- /// <param name="isSideways">Set to true if the text is intended to be
- /// drawn vertically.</param>
- /// <param name="isRightToLeft">Set to TRUE for right-to-left text.</param>
- /// <param name="scriptAnalysis">Script analysis result from AnalyzeScript.</param>
- /// <param name="localeName">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.</param>
- /// <param name="numberSubstitution">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.</param>
- /// <param name="features">An array of pointers to the sets of typographic
- /// features to use in each feature range.</param>
- /// <param name="featureRangeLengths">The length of each feature range, in characters.
- /// The sum of all lengths should be equal to textLength.</param>
- /// <param name="featureRanges">The number of feature ranges.</param>
- /// <param name="maxGlyphCount">The maximum number of glyphs that can be
- /// returned.</param>
- /// <param name="clusterMap">The mapping from character ranges to glyph
- /// ranges.</param>
- /// <param name="textProps">Per-character output properties.</param>
- /// <param name="glyphIndices">Output glyph indices.</param>
- /// <param name="glyphProps">Per-glyph output properties.</param>
- /// <param name="actualGlyphCount">The actual number of glyphs returned if
- /// the call succeeds.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- /// <remarks>
- /// 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.
- /// </remarks>
- 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;
-
- /// <summary>
- /// Place glyphs output from the GetGlyphs method according to the font
- /// and the writing system's rendering rules.
- /// </summary>
- /// <param name="textString">The original string the glyphs came from.</param>
- /// <param name="clusterMap">The mapping from character ranges to glyph
- /// ranges. Returned by GetGlyphs.</param>
- /// <param name="textProps">Per-character properties. Returned by
- /// GetGlyphs.</param>
- /// <param name="textLength">The length of textString.</param>
- /// <param name="glyphIndices">Glyph indices. See GetGlyphs</param>
- /// <param name="glyphProps">Per-glyph properties. See GetGlyphs</param>
- /// <param name="glyphCount">The number of glyphs.</param>
- /// <param name="fontFace">The font face the glyphs came from.</param>
- /// <param name="fontEmSize">Logical font size in DIP's.</param>
- /// <param name="isSideways">Set to true if the text is intended to be
- /// drawn vertically.</param>
- /// <param name="isRightToLeft">Set to TRUE for right-to-left text.</param>
- /// <param name="scriptAnalysis">Script analysis result from AnalyzeScript.</param>
- /// <param name="localeName">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.</param>
- /// <param name="features">An array of pointers to the sets of typographic
- /// features to use in each feature range.</param>
- /// <param name="featureRangeLengths">The length of each feature range, in characters.
- /// The sum of all lengths should be equal to textLength.</param>
- /// <param name="featureRanges">The number of feature ranges.</param>
- /// <param name="glyphAdvances">The advance width of each glyph.</param>
- /// <param name="glyphOffsets">The offset of the origin of each glyph.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- 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;
-
- /// <summary>
- /// Place glyphs output from the GetGlyphs method according to the font
- /// and the writing system's rendering rules.
- /// </summary>
- /// <param name="textString">The original string the glyphs came from.</param>
- /// <param name="clusterMap">The mapping from character ranges to glyph
- /// ranges. Returned by GetGlyphs.</param>
- /// <param name="textProps">Per-character properties. Returned by
- /// GetGlyphs.</param>
- /// <param name="textLength">The length of textString.</param>
- /// <param name="glyphIndices">Glyph indices. See GetGlyphs</param>
- /// <param name="glyphProps">Per-glyph properties. See GetGlyphs</param>
- /// <param name="glyphCount">The number of glyphs.</param>
- /// <param name="fontFace">The font face the glyphs came from.</param>
- /// <param name="fontEmSize">Logical font size in DIP's.</param>
- /// <param name="pixelsPerDip">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.</param>
- /// <param name="transform">Optional transform applied to the glyphs and their positions. This transform is applied after the
- /// scaling specified by the font size and pixelsPerDip.</param>
- /// <param name="useGdiNatural">
- /// 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.
- /// </param>
- /// <param name="isSideways">Set to true if the text is intended to be
- /// drawn vertically.</param>
- /// <param name="isRightToLeft">Set to TRUE for right-to-left text.</param>
- /// <param name="scriptAnalysis">Script analysis result from AnalyzeScript.</param>
- /// <param name="localeName">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.</param>
- /// <param name="features">An array of pointers to the sets of typographic
- /// features to use in each feature range.</param>
- /// <param name="featureRangeLengths">The length of each feature range, in characters.
- /// The sum of all lengths should be equal to textLength.</param>
- /// <param name="featureRanges">The number of feature ranges.</param>
- /// <param name="glyphAdvances">The advance width of each glyph.</param>
- /// <param name="glyphOffsets">The offset of the origin of each glyph.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- 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;
-};
-
-/// <summary>
-/// The DWRITE_GLYPH_RUN structure contains the information needed by renderers
-/// to draw glyph runs. All coordinates are in device independent pixels (DIPs).
-/// </summary>
-struct DWRITE_GLYPH_RUN
-{
- /// <summary>
- /// The physical font face to draw with.
- /// </summary>
- __notnull IDWriteFontFace* fontFace;
-
- /// <summary>
- /// Logical size of the font in DIPs, not points (equals 1/96 inch).
- /// </summary>
- FLOAT fontEmSize;
-
- /// <summary>
- /// The number of glyphs.
- /// </summary>
- UINT32 glyphCount;
-
- /// <summary>
- /// The indices to render.
- /// </summary>
- __field_ecount(glyphCount) UINT16 const* glyphIndices;
-
- /// <summary>
- /// Glyph advance widths.
- /// </summary>
- __field_ecount_opt(glyphCount) FLOAT const* glyphAdvances;
-
- /// <summary>
- /// Glyph offsets.
- /// </summary>
- __field_ecount_opt(glyphCount) DWRITE_GLYPH_OFFSET const* glyphOffsets;
-
- /// <summary>
- /// 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.
- /// </summary>
- BOOL isSideways;
-
- /// <summary>
- /// 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.
- /// </summary>
- UINT32 bidiLevel;
-};
-
-/// <summary>
-/// The DWRITE_GLYPH_RUN_DESCRIPTION structure contains additional properties
-/// related to those in DWRITE_GLYPH_RUN.
-/// </summary>
-struct DWRITE_GLYPH_RUN_DESCRIPTION
-{
- /// <summary>
- /// The locale name associated with this run.
- /// </summary>
- __nullterminated WCHAR const* localeName;
-
- /// <summary>
- /// The text associated with the glyphs.
- /// </summary>
- __field_ecount(stringLength) WCHAR const* string;
-
- /// <summary>
- /// The number of characters (UTF16 code-units).
- /// Note that this may be different than the number of glyphs.
- /// </summary>
- UINT32 stringLength;
-
- /// <summary>
- /// An array of indices to the glyph indices array, of the first glyphs of
- /// all the glyph clusters of the glyphs to render.
- /// </summary>
- __field_ecount(stringLength) UINT16 const* clusterMap;
-
- /// <summary>
- /// Corresponding text position in the original string
- /// this glyph run came from.
- /// </summary>
- UINT32 textPosition;
-};
-
-/// <summary>
-/// The DWRITE_UNDERLINE structure contains about the size and placement of
-/// underlines. All coordinates are in device independent pixels (DIPs).
-/// </summary>
-struct DWRITE_UNDERLINE
-{
- /// <summary>
- /// Width of the underline, measured parallel to the baseline.
- /// </summary>
- FLOAT width;
-
- /// <summary>
- /// Thickness of the underline, measured perpendicular to the
- /// baseline.
- /// </summary>
- FLOAT thickness;
-
- /// <summary>
- /// Offset of the underline from the baseline.
- /// A positive offset represents a position below the baseline and
- /// a negative offset is above.
- /// </summary>
- FLOAT offset;
-
- /// <summary>
- /// Height of the tallest run where the underline applies.
- /// </summary>
- FLOAT runHeight;
-
- /// <summary>
- /// Reading direction of the text associated with the underline. This
- /// value is used to interpret whether the width value runs horizontally
- /// or vertically.
- /// </summary>
- DWRITE_READING_DIRECTION readingDirection;
-
- /// <summary>
- /// 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.
- /// </summary>
- DWRITE_FLOW_DIRECTION flowDirection;
-
- /// <summary>
- /// 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.
- /// </summary>
- __nullterminated WCHAR const* localeName;
-
- /// <summary>
- /// 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.
- /// </summary>
- DWRITE_MEASURING_MODE measuringMode;
-};
-
-/// <summary>
-/// The DWRITE_STRIKETHROUGH structure contains about the size and placement of
-/// strickthroughs. All coordinates are in device independent pixels (DIPs).
-/// </summary>
-struct DWRITE_STRIKETHROUGH
-{
- /// <summary>
- /// Width of the strikethrough, measured parallel to the baseline.
- /// </summary>
- FLOAT width;
-
- /// <summary>
- /// Thickness of the strikethrough, measured perpendicular to the
- /// baseline.
- /// </summary>
- FLOAT thickness;
-
- /// <summary>
- /// Offset of the stikethrough from the baseline.
- /// A positive offset represents a position below the baseline and
- /// a negative offset is above.
- /// </summary>
- FLOAT offset;
-
- /// <summary>
- /// Reading direction of the text associated with the strikethrough. This
- /// value is used to interpret whether the width value runs horizontally
- /// or vertically.
- /// </summary>
- DWRITE_READING_DIRECTION readingDirection;
-
- /// <summary>
- /// 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.
- /// </summary>
- DWRITE_FLOW_DIRECTION flowDirection;
-
- /// <summary>
- /// Locale of the range. Can be pertinent where the locale affects the style.
- /// </summary>
- __nullterminated WCHAR const* localeName;
-
- /// <summary>
- /// 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.
- /// </summary>
- DWRITE_MEASURING_MODE measuringMode;
-};
-
-/// <summary>
-/// The DWRITE_LINE_METRICS structure contains information about a formatted
-/// line of text.
-/// </summary>
-struct DWRITE_LINE_METRICS
-{
- /// <summary>
- /// The number of total text positions in the line.
- /// This includes any trailing whitespace and newline characters.
- /// </summary>
- UINT32 length;
-
- /// <summary>
- /// The number of whitespace positions at the end of the line. Newline
- /// sequences are considered whitespace.
- /// </summary>
- UINT32 trailingWhitespaceLength;
-
- /// <summary>
- /// 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.
- /// </summary>
- UINT32 newlineLength;
-
- /// <summary>
- /// Height of the line as measured from top to bottom.
- /// </summary>
- FLOAT height;
-
- /// <summary>
- /// Distance from the top of the line to its baseline.
- /// </summary>
- FLOAT baseline;
-
- /// <summary>
- /// The line is trimmed.
- /// </summary>
- BOOL isTrimmed;
-};
-
-
-/// <summary>
-/// The DWRITE_CLUSTER_METRICS structure contains information about a glyph cluster.
-/// </summary>
-struct DWRITE_CLUSTER_METRICS
-{
- /// <summary>
- /// The total advance width of all glyphs in the cluster.
- /// </summary>
- FLOAT width;
-
- /// <summary>
- /// The number of text positions in the cluster.
- /// </summary>
- UINT16 length;
-
- /// <summary>
- /// Indicate whether line can be broken right after the cluster.
- /// </summary>
- UINT16 canWrapLineAfter : 1;
-
- /// <summary>
- /// Indicate whether the cluster corresponds to whitespace character.
- /// </summary>
- UINT16 isWhitespace : 1;
-
- /// <summary>
- /// Indicate whether the cluster corresponds to a newline character.
- /// </summary>
- UINT16 isNewline : 1;
-
- /// <summary>
- /// Indicate whether the cluster corresponds to soft hyphen character.
- /// </summary>
- UINT16 isSoftHyphen : 1;
-
- /// <summary>
- /// Indicate whether the cluster is read from right to left.
- /// </summary>
- UINT16 isRightToLeft : 1;
-
- UINT16 padding : 11;
-};
-
-
-/// <summary>
-/// Overall metrics associated with text after layout.
-/// All coordinates are in device independent pixels (DIPs).
-/// </summary>
-struct DWRITE_TEXT_METRICS
-{
- /// <summary>
- /// Left-most point of formatted text relative to layout box
- /// (excluding any glyph overhang).
- /// </summary>
- FLOAT left;
-
- /// <summary>
- /// Top-most point of formatted text relative to layout box
- /// (excluding any glyph overhang).
- /// </summary>
- FLOAT top;
-
- /// <summary>
- /// The width of the formatted text ignoring trailing whitespace
- /// at the end of each line.
- /// </summary>
- FLOAT width;
-
- /// <summary>
- /// The width of the formatted text taking into account the
- /// trailing whitespace at the end of each line.
- /// </summary>
- FLOAT widthIncludingTrailingWhitespace;
-
- /// <summary>
- /// The height of the formatted text. The height of an empty string
- /// is determined by the size of the default font's line height.
- /// </summary>
- FLOAT height;
-
- /// <summary>
- /// 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.
- /// </summary>
- FLOAT layoutWidth;
-
- /// <summary>
- /// Initial height given to the layout. Depending on the length of the
- /// text, it may be larger or smaller than the text content height.
- /// </summary>
- FLOAT layoutHeight;
-
- /// <summary>
- /// 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.
- /// </summary>
- UINT32 maxBidiReorderingDepth;
-
- /// <summary>
- /// Total number of lines.
- /// </summary>
- UINT32 lineCount;
-};
-
-
-/// <summary>
-/// Properties describing the geometric measurement of an
-/// application-defined inline object.
-/// </summary>
-struct DWRITE_INLINE_OBJECT_METRICS
-{
- /// <summary>
- /// Width of the inline object.
- /// </summary>
- FLOAT width;
-
- /// <summary>
- /// Height of the inline object as measured from top to bottom.
- /// </summary>
- FLOAT height;
-
- /// <summary>
- /// 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.
- /// </summary>
- FLOAT baseline;
-
- /// <summary>
- /// Flag indicating whether the object is to be placed upright or alongside the text baseline
- /// for vertical text.
- /// </summary>
- BOOL supportsSideways;
-};
-
-
-/// <summary>
-/// The DWRITE_OVERHANG_METRICS structure holds how much any visible pixels
-/// (in DIPs) overshoot each side of the layout or inline objects.
-/// </summary>
-/// <remarks>
-/// 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.
-/// </remarks>
-struct DWRITE_OVERHANG_METRICS
-{
- /// <summary>
- /// The distance from the left-most visible DIP to its left alignment edge.
- /// </summary>
- FLOAT left;
-
- /// <summary>
- /// The distance from the top-most visible DIP to its top alignment edge.
- /// </summary>
- FLOAT top;
-
- /// <summary>
- /// The distance from the right-most visible DIP to its right alignment edge.
- /// </summary>
- FLOAT right;
-
- /// <summary>
- /// The distance from the bottom-most visible DIP to its bottom alignment edge.
- /// </summary>
- FLOAT bottom;
-};
-
-
-/// <summary>
-/// Geometry enclosing of text positions.
-/// </summary>
-struct DWRITE_HIT_TEST_METRICS
-{
- /// <summary>
- /// First text position within the geometry.
- /// </summary>
- UINT32 textPosition;
-
- /// <summary>
- /// Number of text positions within the geometry.
- /// </summary>
- UINT32 length;
-
- /// <summary>
- /// Left position of the top-left coordinate of the geometry.
- /// </summary>
- FLOAT left;
-
- /// <summary>
- /// Top position of the top-left coordinate of the geometry.
- /// </summary>
- FLOAT top;
-
- /// <summary>
- /// Geometry's width.
- /// </summary>
- FLOAT width;
-
- /// <summary>
- /// Geometry's height.
- /// </summary>
- FLOAT height;
-
- /// <summary>
- /// Bidi level of text positions enclosed within the geometry.
- /// </summary>
- UINT32 bidiLevel;
-
- /// <summary>
- /// Geometry encloses text?
- /// </summary>
- BOOL isText;
-
- /// <summary>
- /// Range is trimmed.
- /// </summary>
- BOOL isTrimmed;
-};
-
-
-interface IDWriteTextRenderer;
-
-
-/// <summary>
-/// The IDWriteInlineObject interface wraps an application defined inline graphic,
-/// allowing DWrite to query metrics as if it was a glyph inline with the text.
-/// </summary>
-interface DWRITE_DECLARE_INTERFACE("8339FDE3-106F-47ab-8373-1C6295EB10B3") IDWriteInlineObject : public IUnknown
-{
- /// <summary>
- /// 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.
- /// </summary>
- /// <param name="clientDrawingContext">The context passed to IDWriteTextLayout::Draw.</param>
- /// <param name="renderer">The renderer passed to IDWriteTextLayout::Draw as the object's containing parent.</param>
- /// <param name="originX">X-coordinate at the top-left corner of the inline object.</param>
- /// <param name="originY">Y-coordinate at the top-left corner of the inline object.</param>
- /// <param name="isSideways">The object should be drawn on its side.</param>
- /// <param name="isRightToLeft">The object is in an right-to-left context and should be drawn flipped.</param>
- /// <param name="clientDrawingEffect">The drawing effect set in IDWriteTextLayout::SetDrawingEffect.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(Draw)(
- __maybenull void* clientDrawingContext,
- IDWriteTextRenderer* renderer,
- FLOAT originX,
- FLOAT originY,
- BOOL isSideways,
- BOOL isRightToLeft,
- __maybenull IUnknown* clientDrawingEffect
- ) PURE;
-
- /// <summary>
- /// TextLayout calls this callback function to get the measurement of the inline object.
- /// </summary>
- /// <param name="metrics">Returned metrics</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetMetrics)(
- __out DWRITE_INLINE_OBJECT_METRICS* metrics
- ) PURE;
-
- /// <summary>
- /// 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.
- /// </summary>
- /// <param name="overhangs">Overshoot of visible extents (in DIPs) outside the object.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- /// <remarks>
- /// 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.
- /// </remarks>
- STDMETHOD(GetOverhangMetrics)(
- __out DWRITE_OVERHANG_METRICS* overhangs
- ) PURE;
-
- /// <summary>
- /// Layout uses this to determine the line breaking behavior of the inline object
- /// amidst the text.
- /// </summary>
- /// <param name="breakConditionBefore">Line-breaking condition between the object and the content immediately preceding it.</param>
- /// <param name="breakConditionAfter" >Line-breaking condition between the object and the content immediately following it.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetBreakConditions)(
- __out DWRITE_BREAK_CONDITION* breakConditionBefore,
- __out DWRITE_BREAK_CONDITION* breakConditionAfter
- ) PURE;
-};
-
-/// <summary>
-/// The IDWritePixelSnapping interface defines the pixel snapping properties of a text renderer.
-/// </summary>
-interface DWRITE_DECLARE_INTERFACE("eaf3a2da-ecf4-4d24-b644-b34f6842024b") IDWritePixelSnapping : public IUnknown
-{
- /// <summary>
- /// Determines whether pixel snapping is disabled. The recommended default is FALSE,
- /// unless doing animation that requires subpixel vertical placement.
- /// </summary>
- /// <param name="clientDrawingContext">The context passed to IDWriteTextLayout::Draw.</param>
- /// <param name="isDisabled">Receives TRUE if pixel snapping is disabled or FALSE if it not.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(IsPixelSnappingDisabled)(
- __maybenull void* clientDrawingContext,
- __out BOOL* isDisabled
- ) PURE;
-
- /// <summary>
- /// Gets the current transform that maps abstract coordinates to DIPs,
- /// which may disable pixel snapping upon any rotation or shear.
- /// </summary>
- /// <param name="clientDrawingContext">The context passed to IDWriteTextLayout::Draw.</param>
- /// <param name="transform">Receives the transform.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetCurrentTransform)(
- __maybenull void* clientDrawingContext,
- __out DWRITE_MATRIX* transform
- ) PURE;
-
- /// <summary>
- /// 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).
- /// </summary>
- /// <param name="clientDrawingContext">The context passed to IDWriteTextLayout::Draw.</param>
- /// <param name="pixelsPerDip">Receives the number of physical pixels per DIP.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetPixelsPerDip)(
- __maybenull void* clientDrawingContext,
- __out FLOAT* pixelsPerDip
- ) PURE;
-};
-
-/// <summary>
-/// The IDWriteTextLayout interface represents a set of application-defined
-/// callbacks that perform rendering of text, inline objects, and decorations
-/// such as underlines.
-/// </summary>
-interface DWRITE_DECLARE_INTERFACE("ef8a8135-5cc6-45fe-8825-c5a0724eb819") IDWriteTextRenderer : public IDWritePixelSnapping
-{
- /// <summary>
- /// IDWriteTextLayout::Draw calls this function to instruct the client to
- /// render a run of glyphs.
- /// </summary>
- /// <param name="clientDrawingContext">The context passed to
- /// IDWriteTextLayout::Draw.</param>
- /// <param name="baselineOriginX">X-coordinate of the baseline.</param>
- /// <param name="baselineOriginY">Y-coordinate of the baseline.</param>
- /// <param name="measuringMode">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
- /// </param>
- /// <param name="glyphRun">The glyph run to draw.</param>
- /// <param name="glyphRunDescription">Properties of the characters
- /// associated with this run.</param>
- /// <param name="clientDrawingEffect">The drawing effect set in
- /// IDWriteTextLayout::SetDrawingEffect.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- 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;
-
- /// <summary>
- /// IDWriteTextLayout::Draw calls this function to instruct the client to draw
- /// an underline.
- /// </summary>
- /// <param name="clientDrawingContext">The context passed to
- /// IDWriteTextLayout::Draw.</param>
- /// <param name="baselineOriginX">X-coordinate of the baseline.</param>
- /// <param name="baselineOriginY">Y-coordinate of the baseline.</param>
- /// <param name="underline">Underline logical information.</param>
- /// <param name="clientDrawingEffect">The drawing effect set in
- /// IDWriteTextLayout::SetDrawingEffect.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- /// <remarks>
- /// 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.
- /// </remarks>
- STDMETHOD(DrawUnderline)(
- __maybenull void* clientDrawingContext,
- FLOAT baselineOriginX,
- FLOAT baselineOriginY,
- __in DWRITE_UNDERLINE const* underline,
- __maybenull IUnknown* clientDrawingEffect
- ) PURE;
-
- /// <summary>
- /// IDWriteTextLayout::Draw calls this function to instruct the client to draw
- /// a strikethrough.
- /// </summary>
- /// <param name="clientDrawingContext">The context passed to
- /// IDWriteTextLayout::Draw.</param>
- /// <param name="baselineOriginX">X-coordinate of the baseline.</param>
- /// <param name="baselineOriginY">Y-coordinate of the baseline.</param>
- /// <param name="strikethrough">Strikethrough logical information.</param>
- /// <param name="clientDrawingEffect">The drawing effect set in
- /// IDWriteTextLayout::SetDrawingEffect.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- /// <remarks>
- /// 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.
- /// </remarks>
- STDMETHOD(DrawStrikethrough)(
- __maybenull void* clientDrawingContext,
- FLOAT baselineOriginX,
- FLOAT baselineOriginY,
- __in DWRITE_STRIKETHROUGH const* strikethrough,
- __maybenull IUnknown* clientDrawingEffect
- ) PURE;
-
- /// <summary>
- /// IDWriteTextLayout::Draw calls this application callback when it needs to
- /// draw an inline object.
- /// </summary>
- /// <param name="clientDrawingContext">The context passed to IDWriteTextLayout::Draw.</param>
- /// <param name="originX">X-coordinate at the top-left corner of the inline object.</param>
- /// <param name="originY">Y-coordinate at the top-left corner of the inline object.</param>
- /// <param name="inlineObject">The object set using IDWriteTextLayout::SetInlineObject.</param>
- /// <param name="isSideways">The object should be drawn on its side.</param>
- /// <param name="isRightToLeft">The object is in an right-to-left context and should be drawn flipped.</param>
- /// <param name="clientDrawingEffect">The drawing effect set in
- /// IDWriteTextLayout::SetDrawingEffect.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- /// <remarks>
- /// 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).
- /// </remarks>
- STDMETHOD(DrawInlineObject)(
- __maybenull void* clientDrawingContext,
- FLOAT originX,
- FLOAT originY,
- IDWriteInlineObject* inlineObject,
- BOOL isSideways,
- BOOL isRightToLeft,
- __maybenull IUnknown* clientDrawingEffect
- ) PURE;
-};
-
-/// <summary>
-/// The IDWriteTextLayout interface represents a block of text after it has
-/// been fully analyzed and formatted.
-///
-/// All coordinates are in device independent pixels (DIPs).
-/// </summary>
-interface DWRITE_DECLARE_INTERFACE("53737037-6d14-410b-9bfe-0b182bb70961") IDWriteTextLayout : public IDWriteTextFormat
-{
- /// <summary>
- /// Set layout maximum width
- /// </summary>
- /// <param name="maxWidth">Layout maximum width</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(SetMaxWidth)(
- FLOAT maxWidth
- ) PURE;
-
- /// <summary>
- /// Set layout maximum height
- /// </summary>
- /// <param name="maxHeight">Layout maximum height</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(SetMaxHeight)(
- FLOAT maxHeight
- ) PURE;
-
- /// <summary>
- /// Set the font collection.
- /// </summary>
- /// <param name="fontCollection">The font collection to set</param>
- /// <param name="textRange">Text range to which this change applies.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(SetFontCollection)(
- IDWriteFontCollection* fontCollection,
- DWRITE_TEXT_RANGE textRange
- ) PURE;
-
- /// <summary>
- /// Set null-terminated font family name.
- /// </summary>
- /// <param name="fontFamilyName">Font family name</param>
- /// <param name="textRange">Text range to which this change applies.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(SetFontFamilyName)(
- __in_z WCHAR const* fontFamilyName,
- DWRITE_TEXT_RANGE textRange
- ) PURE;
-
- /// <summary>
- /// Set font weight.
- /// </summary>
- /// <param name="fontWeight">Font weight</param>
- /// <param name="textRange">Text range to which this change applies.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(SetFontWeight)(
- DWRITE_FONT_WEIGHT fontWeight,
- DWRITE_TEXT_RANGE textRange
- ) PURE;
-
- /// <summary>
- /// Set font style.
- /// </summary>
- /// <param name="fontStyle">Font style</param>
- /// <param name="textRange">Text range to which this change applies.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(SetFontStyle)(
- DWRITE_FONT_STYLE fontStyle,
- DWRITE_TEXT_RANGE textRange
- ) PURE;
-
- /// <summary>
- /// Set font stretch.
- /// </summary>
- /// <param name="fontStretch">font stretch</param>
- /// <param name="textRange">Text range to which this change applies.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(SetFontStretch)(
- DWRITE_FONT_STRETCH fontStretch,
- DWRITE_TEXT_RANGE textRange
- ) PURE;
-
- /// <summary>
- /// Set font em height.
- /// </summary>
- /// <param name="fontSize">Font em height</param>
- /// <param name="textRange">Text range to which this change applies.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(SetFontSize)(
- FLOAT fontSize,
- DWRITE_TEXT_RANGE textRange
- ) PURE;
-
- /// <summary>
- /// Set underline.
- /// </summary>
- /// <param name="hasUnderline">The Boolean flag indicates whether underline takes place</param>
- /// <param name="textRange">Text range to which this change applies.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(SetUnderline)(
- BOOL hasUnderline,
- DWRITE_TEXT_RANGE textRange
- ) PURE;
-
- /// <summary>
- /// Set strikethrough.
- /// </summary>
- /// <param name="hasStrikethrough">The Boolean flag indicates whether strikethrough takes place</param>
- /// <param name="textRange">Text range to which this change applies.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(SetStrikethrough)(
- BOOL hasStrikethrough,
- DWRITE_TEXT_RANGE textRange
- ) PURE;
-
- /// <summary>
- /// Set application-defined drawing effect.
- /// </summary>
- /// <param name="drawingEffect">Pointer to an application-defined drawing effect.</param>
- /// <param name="textRange">Text range to which this change applies.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- /// <remarks>
- /// 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.
- /// </remarks>
- STDMETHOD(SetDrawingEffect)(
- IUnknown* drawingEffect,
- DWRITE_TEXT_RANGE textRange
- ) PURE;
-
- /// <summary>
- /// Set inline object.
- /// </summary>
- /// <param name="inlineObject">Pointer to an application-implemented inline object.</param>
- /// <param name="textRange">Text range to which this change applies.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- /// <remarks>
- /// 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.
- /// </remarks>
- STDMETHOD(SetInlineObject)(
- IDWriteInlineObject* inlineObject,
- DWRITE_TEXT_RANGE textRange
- ) PURE;
-
- /// <summary>
- /// Set font typography features.
- /// </summary>
- /// <param name="typography">Pointer to font typography setting.</param>
- /// <param name="textRange">Text range to which this change applies.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(SetTypography)(
- IDWriteTypography* typography,
- DWRITE_TEXT_RANGE textRange
- ) PURE;
-
- /// <summary>
- /// Set locale name.
- /// </summary>
- /// <param name="localeName">Locale name</param>
- /// <param name="textRange">Text range to which this change applies.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(SetLocaleName)(
- __in_z WCHAR const* localeName,
- DWRITE_TEXT_RANGE textRange
- ) PURE;
-
- /// <summary>
- /// Get layout maximum width
- /// </summary>
- STDMETHOD_(FLOAT, GetMaxWidth)() PURE;
-
- /// <summary>
- /// Get layout maximum height
- /// </summary>
- STDMETHOD_(FLOAT, GetMaxHeight)() PURE;
-
- /// <summary>
- /// Get the font collection where the current position is at.
- /// </summary>
- /// <param name="currentPosition">The current text position.</param>
- /// <param name="fontCollection">The current font collection</param>
- /// <param name="textRange">Text range to which this change applies.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetFontCollection)(
- UINT32 currentPosition,
- __out IDWriteFontCollection** fontCollection,
- __out_opt DWRITE_TEXT_RANGE* textRange = NULL
- ) PURE;
-
- /// <summary>
- /// Get the length of the font family name where the current position is at.
- /// </summary>
- /// <param name="currentPosition">The current text position.</param>
- /// <param name="nameLength">Size of the character array in character count not including the terminated NULL character.</param>
- /// <param name="textRange">The position range of the current format.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetFontFamilyNameLength)(
- UINT32 currentPosition,
- __out UINT32* nameLength,
- __out_opt DWRITE_TEXT_RANGE* textRange = NULL
- ) PURE;
-
- /// <summary>
- /// Copy the font family name where the current position is at.
- /// </summary>
- /// <param name="currentPosition">The current text position.</param>
- /// <param name="fontFamilyName">Character array that receives the current font family name</param>
- /// <param name="nameSize">Size of the character array in character count including the terminated NULL character.</param>
- /// <param name="textRange">The position range of the current format.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetFontFamilyName)(
- UINT32 currentPosition,
- __out_ecount_z(nameSize) WCHAR* fontFamilyName,
- UINT32 nameSize,
- __out_opt DWRITE_TEXT_RANGE* textRange = NULL
- ) PURE;
-
- /// <summary>
- /// Get the font weight where the current position is at.
- /// </summary>
- /// <param name="currentPosition">The current text position.</param>
- /// <param name="fontWeight">The current font weight</param>
- /// <param name="textRange">The position range of the current format.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetFontWeight)(
- UINT32 currentPosition,
- __out DWRITE_FONT_WEIGHT* fontWeight,
- __out_opt DWRITE_TEXT_RANGE* textRange = NULL
- ) PURE;
-
- /// <summary>
- /// Get the font style where the current position is at.
- /// </summary>
- /// <param name="currentPosition">The current text position.</param>
- /// <param name="fontStyle">The current font style</param>
- /// <param name="textRange">The position range of the current format.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetFontStyle)(
- UINT32 currentPosition,
- __out DWRITE_FONT_STYLE* fontStyle,
- __out_opt DWRITE_TEXT_RANGE* textRange = NULL
- ) PURE;
-
- /// <summary>
- /// Get the font stretch where the current position is at.
- /// </summary>
- /// <param name="currentPosition">The current text position.</param>
- /// <param name="fontStretch">The current font stretch</param>
- /// <param name="textRange">The position range of the current format.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetFontStretch)(
- UINT32 currentPosition,
- __out DWRITE_FONT_STRETCH* fontStretch,
- __out_opt DWRITE_TEXT_RANGE* textRange = NULL
- ) PURE;
-
- /// <summary>
- /// Get the font em height where the current position is at.
- /// </summary>
- /// <param name="currentPosition">The current text position.</param>
- /// <param name="fontSize">The current font em height</param>
- /// <param name="textRange">The position range of the current format.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetFontSize)(
- UINT32 currentPosition,
- __out FLOAT* fontSize,
- __out_opt DWRITE_TEXT_RANGE* textRange = NULL
- ) PURE;
-
- /// <summary>
- /// Get the underline presence where the current position is at.
- /// </summary>
- /// <param name="currentPosition">The current text position.</param>
- /// <param name="hasUnderline">The Boolean flag indicates whether text is underlined.</param>
- /// <param name="textRange">The position range of the current format.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetUnderline)(
- UINT32 currentPosition,
- __out BOOL* hasUnderline,
- __out_opt DWRITE_TEXT_RANGE* textRange = NULL
- ) PURE;
-
- /// <summary>
- /// Get the strikethrough presence where the current position is at.
- /// </summary>
- /// <param name="currentPosition">The current text position.</param>
- /// <param name="hasStrikethrough">The Boolean flag indicates whether text has strikethrough.</param>
- /// <param name="textRange">The position range of the current format.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetStrikethrough)(
- UINT32 currentPosition,
- __out BOOL* hasStrikethrough,
- __out_opt DWRITE_TEXT_RANGE* textRange = NULL
- ) PURE;
-
- /// <summary>
- /// Get the application-defined drawing effect where the current position is at.
- /// </summary>
- /// <param name="currentPosition">The current text position.</param>
- /// <param name="drawingEffect">The current application-defined drawing effect.</param>
- /// <param name="textRange">The position range of the current format.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetDrawingEffect)(
- UINT32 currentPosition,
- __out IUnknown** drawingEffect,
- __out_opt DWRITE_TEXT_RANGE* textRange = NULL
- ) PURE;
-
- /// <summary>
- /// Get the inline object at the given position.
- /// </summary>
- /// <param name="currentPosition">The given text position.</param>
- /// <param name="inlineObject">The inline object.</param>
- /// <param name="textRange">The position range of the current format.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetInlineObject)(
- UINT32 currentPosition,
- __out IDWriteInlineObject** inlineObject,
- __out_opt DWRITE_TEXT_RANGE* textRange = NULL
- ) PURE;
-
- /// <summary>
- /// Get the typography setting where the current position is at.
- /// </summary>
- /// <param name="currentPosition">The current text position.</param>
- /// <param name="typography">The current typography setting.</param>
- /// <param name="textRange">The position range of the current format.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetTypography)(
- UINT32 currentPosition,
- __out IDWriteTypography** typography,
- __out_opt DWRITE_TEXT_RANGE* textRange = NULL
- ) PURE;
-
- /// <summary>
- /// Get the length of the locale name where the current position is at.
- /// </summary>
- /// <param name="currentPosition">The current text position.</param>
- /// <param name="nameLength">Size of the character array in character count not including the terminated NULL character.</param>
- /// <param name="textRange">The position range of the current format.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetLocaleNameLength)(
- UINT32 currentPosition,
- __out UINT32* nameLength,
- __out_opt DWRITE_TEXT_RANGE* textRange = NULL
- ) PURE;
-
- /// <summary>
- /// Get the locale name where the current position is at.
- /// </summary>
- /// <param name="currentPosition">The current text position.</param>
- /// <param name="localeName">Character array that receives the current locale name</param>
- /// <param name="nameSize">Size of the character array in character count including the terminated NULL character.</param>
- /// <param name="textRange">The position range of the current format.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetLocaleName)(
- UINT32 currentPosition,
- __out_ecount_z(nameSize) WCHAR* localeName,
- UINT32 nameSize,
- __out_opt DWRITE_TEXT_RANGE* textRange = NULL
- ) PURE;
-
- /// <summary>
- /// Initiate drawing of the text.
- /// </summary>
- /// <param name="clientDrawingContext">An application defined value
- /// included in rendering callbacks.</param>
- /// <param name="renderer">The set of application-defined callbacks that do
- /// the actual rendering.</param>
- /// <param name="originX">X-coordinate of the layout's left side.</param>
- /// <param name="originY">Y-coordinate of the layout's top side.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(Draw)(
- __maybenull void* clientDrawingContext,
- IDWriteTextRenderer* renderer,
- FLOAT originX,
- FLOAT originY
- ) PURE;
-
- /// <summary>
- /// GetLineMetrics returns properties of each line.
- /// </summary>
- /// <param name="lineMetrics">The array to fill with line information.</param>
- /// <param name="maxLineCount">The maximum size of the lineMetrics array.</param>
- /// <param name="actualLineCount">The actual size of the lineMetrics
- /// array that is needed.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- /// <remarks>
- /// 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.
- /// </remarks>
- STDMETHOD(GetLineMetrics)(
- __out_ecount_opt(maxLineCount) DWRITE_LINE_METRICS* lineMetrics,
- UINT32 maxLineCount,
- __out UINT32* actualLineCount
- ) PURE;
-
- /// <summary>
- /// GetMetrics retrieves overall metrics for the formatted string.
- /// </summary>
- /// <param name="textMetrics">The returned metrics.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- /// <remarks>
- /// 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.
- /// </remarks>
- STDMETHOD(GetMetrics)(
- __out DWRITE_TEXT_METRICS* textMetrics
- ) PURE;
-
- /// <summary>
- /// GetOverhangMetrics returns the overhangs (in DIPs) of the layout and all
- /// objects contained in it, including text glyphs and inline objects.
- /// </summary>
- /// <param name="overhangs">Overshoots of visible extents (in DIPs) outside the layout.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- /// <remarks>
- /// 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.
- /// </remarks>
- STDMETHOD(GetOverhangMetrics)(
- __out DWRITE_OVERHANG_METRICS* overhangs
- ) PURE;
-
- /// <summary>
- /// Retrieve logical properties and measurement of each cluster.
- /// </summary>
- /// <param name="clusterMetrics">The array to fill with cluster information.</param>
- /// <param name="maxClusterCount">The maximum size of the clusterMetrics array.</param>
- /// <param name="actualClusterCount">The actual size of the clusterMetrics array that is needed.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- /// <remarks>
- /// 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.
- /// </remarks>
- STDMETHOD(GetClusterMetrics)(
- __out_ecount_opt(maxClusterCount) DWRITE_CLUSTER_METRICS* clusterMetrics,
- UINT32 maxClusterCount,
- __out UINT32* actualClusterCount
- ) PURE;
-
- /// <summary>
- /// Determines the minimum possible width the layout can be set to without
- /// emergency breaking between the characters of whole words.
- /// </summary>
- /// <param name="minWidth">Minimum width.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(DetermineMinWidth)(
- __out FLOAT* minWidth
- ) PURE;
-
- /// <summary>
- /// 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.
- /// </summary>
- /// <param name="pointX">X coordinate to hit-test, relative to the top-left location of the layout box.</param>
- /// <param name="pointY">Y coordinate to hit-test, relative to the top-left location of the layout box.</param>
- /// <param name="isTrailingHit">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. </param>
- /// <param name="isInside">Output flag indicating whether the hit-test location is inside the text string.
- /// When false, the position nearest the text's edge is returned.</param>
- /// <param name="hitTestMetrics">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.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(HitTestPoint)(
- FLOAT pointX,
- FLOAT pointY,
- __out BOOL* isTrailingHit,
- __out BOOL* isInside,
- __out DWRITE_HIT_TEST_METRICS* hitTestMetrics
- ) PURE;
-
- /// <summary>
- /// 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.
- /// </summary>
- /// <param name="textPosition">Text position to get the coordinate of.</param>
- /// <param name="isTrailingHit">Flag indicating whether the location is of the leading or the trailing side of the specified text position. </param>
- /// <param name="pointX">Output caret X, relative to the top-left of the layout box.</param>
- /// <param name="pointY">Output caret Y, relative to the top-left of the layout box.</param>
- /// <param name="hitTestMetrics">Output geometry fully enclosing the specified text position.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- /// <remarks>
- /// 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.
- /// </remarks>
- STDMETHOD(HitTestTextPosition)(
- UINT32 textPosition,
- BOOL isTrailingHit,
- __out FLOAT* pointX,
- __out FLOAT* pointY,
- __out DWRITE_HIT_TEST_METRICS* hitTestMetrics
- ) PURE;
-
- /// <summary>
- /// 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.
- /// </summary>
- /// <param name="textPosition">First text position of the specified range.</param>
- /// <param name="textLength">Number of positions of the specified range.</param>
- /// <param name="originX">Offset of the X origin (left of the layout box) which is added to each of the hit-test metrics returned.</param>
- /// <param name="originY">Offset of the Y origin (top of the layout box) which is added to each of the hit-test metrics returned.</param>
- /// <param name="hitTestMetrics">Pointer to a buffer of the output geometry fully enclosing the specified position range.</param>
- /// <param name="maxHitTestMetricsCount">Maximum number of distinct metrics it could hold in its buffer memory.</param>
- /// <param name="actualHitTestMetricsCount">Actual number of metrics returned or needed.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- /// <remarks>
- /// 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.
- /// </remarks>
- 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;
-};
-
-/// <summary>
-/// Encapsulates a 32-bit device independent bitmap and device context, which can be used for rendering glyphs.
-/// </summary>
-interface DWRITE_DECLARE_INTERFACE("5e5a32a3-8dff-4773-9ff6-0696eab77267") IDWriteBitmapRenderTarget : public IUnknown
-{
- /// <summary>
- /// Draws a run of glyphs to the bitmap.
- /// </summary>
- /// <param name="baselineOriginX">Horizontal position of the baseline origin, in DIPs, relative to the upper-left corner of the DIB.</param>
- /// <param name="baselineOriginY">Vertical position of the baseline origin, in DIPs, relative to the upper-left corner of the DIB.</param>
- /// <param name="measuringMode">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.
- /// </param>
- /// <param name="glyphRun">Structure containing the properties of the glyph run.</param>
- /// <param name="renderingParams">Object that controls rendering behavior.</param>
- /// <param name="textColor">Specifies the foreground color of the text.</param>
- /// <param name="blackBoxRect">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.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- 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;
-
- /// <summary>
- /// Gets a handle to the memory device context.
- /// </summary>
- /// <returns>
- /// Returns the device context handle.
- /// </returns>
- /// <remarks>
- /// 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.
- /// </remarks>
- STDMETHOD_(HDC, GetMemoryDC)() PURE;
-
- /// <summary>
- /// 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.
- /// </summary>
- /// <returns>
- /// Returns the number of bitmap pixels per DIP.
- /// </returns>
- STDMETHOD_(FLOAT, GetPixelsPerDip)() PURE;
-
- /// <summary>
- /// 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.
- /// </summary>
- /// <param name="pixelsPerDip">Specifies the number of pixels per DIP.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(SetPixelsPerDip)(
- FLOAT pixelsPerDip
- ) PURE;
-
- /// <summary>
- /// 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.
- /// </summary>
- /// <param name="transform">Receives the transform.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetCurrentTransform)(
- __out DWRITE_MATRIX* transform
- ) PURE;
-
- /// <summary>
- /// Sets the transform that maps abstract coordinate to DIPs. This does not affect the world
- /// transform of the underlying device context.
- /// </summary>
- /// <param name="transform">Specifies the new transform. This parameter can be NULL, in which
- /// case the identity transform is implied.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(SetCurrentTransform)(
- __in_opt DWRITE_MATRIX const* transform
- ) PURE;
-
- /// <summary>
- /// Gets the dimensions of the bitmap.
- /// </summary>
- /// <param name="size">Receives the size of the bitmap in pixels.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetSize)(
- __out SIZE* size
- ) PURE;
-
- /// <summary>
- /// Resizes the bitmap.
- /// </summary>
- /// <param name="width">New bitmap width, in pixels.</param>
- /// <param name="height">New bitmap height, in pixels.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(Resize)(
- UINT32 width,
- UINT32 height
- ) PURE;
-};
-
-/// <summary>
-/// The GDI interop interface provides interoperability with GDI.
-/// </summary>
-interface DWRITE_DECLARE_INTERFACE("1edd9491-9853-4299-898f-6432983b6f3a") IDWriteGdiInterop : public IUnknown
-{
- /// <summary>
- /// Creates a font object that matches the properties specified by the LOGFONT structure.
- /// </summary>
- /// <param name="logFont">Structure containing a GDI-compatible font description.</param>
- /// <param name="font">Receives a newly created font object if successful, or NULL in case of error.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(CreateFontFromLOGFONT)(
- __in LOGFONTW const* logFont,
- __out IDWriteFont** font
- ) PURE;
-
- /// <summary>
- /// Initializes a LOGFONT structure based on the GDI-compatible properties of the specified font.
- /// </summary>
- /// <param name="font">Specifies a font in the system font collection.</param>
- /// <param name="logFont">Structure that receives a GDI-compatible font description.</param>
- /// <param name="isSystemFont">Contains TRUE if the specified font object is part of the system font collection
- /// or FALSE otherwise.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(ConvertFontToLOGFONT)(
- IDWriteFont* font,
- __out LOGFONTW* logFont,
- __out BOOL* isSystemFont
- ) PURE;
-
- /// <summary>
- /// Initializes a LOGFONT structure based on the GDI-compatible properties of the specified font.
- /// </summary>
- /// <param name="font">Specifies a font face.</param>
- /// <param name="logFont">Structure that receives a GDI-compatible font description.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(ConvertFontFaceToLOGFONT)(
- IDWriteFontFace* font,
- __out LOGFONTW* logFont
- ) PURE;
-
- /// <summary>
- /// Creates a font face object that corresponds to the currently selected HFONT.
- /// </summary>
- /// <param name="hdc">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.</param>
- /// <param name="fontFace">Contains the newly created font face object, or NULL in case of failure.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(CreateFontFaceFromHdc)(
- HDC hdc,
- __out IDWriteFontFace** fontFace
- ) PURE;
-
- /// <summary>
- /// Creates an object that encapsulates a bitmap and memory DC which can be used for rendering glyphs.
- /// </summary>
- /// <param name="hdc">Optional device context used to create a compatible memory DC.</param>
- /// <param name="width">Width of the bitmap.</param>
- /// <param name="height">Height of the bitmap.</param>
- /// <param name="renderTarget">Receives a pointer to the newly created render target.</param>
- STDMETHOD(CreateBitmapRenderTarget)(
- __in_opt HDC hdc,
- UINT32 width,
- UINT32 height,
- __out IDWriteBitmapRenderTarget** renderTarget
- ) PURE;
-};
-
-/// <summary>
-/// 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.
-/// </summary>
-enum DWRITE_TEXTURE_TYPE
-{
- /// <summary>
- /// 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.
- /// </summary>
- DWRITE_TEXTURE_ALIASED_1x1,
-
- /// <summary>
- /// 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.
- /// </summary>
- DWRITE_TEXTURE_CLEARTYPE_3x1
-};
-
-/// <summary>
-/// Maximum alpha value in a texture returned by IDWriteGlyphRunAnalysis::CreateAlphaTexture.
-/// </summary>
-#define DWRITE_ALPHA_MAX 255
-
-/// <summary>
-/// Interface that encapsulates information used to render a glyph run.
-/// </summary>
-interface DWRITE_DECLARE_INTERFACE("7d97dbf7-e085-42d4-81e3-6a883bded118") IDWriteGlyphRunAnalysis : public IUnknown
-{
- /// <summary>
- /// Gets the bounding rectangle of the physical pixels affected by the glyph run.
- /// </summary>
- /// <param name="textureType">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.</param>
- /// <param name="textureBounds">Receives the bounding rectangle, or an empty rectangle if there are no glyphs
- /// if the specified type.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetAlphaTextureBounds)(
- DWRITE_TEXTURE_TYPE textureType,
- __out RECT* textureBounds
- ) PURE;
-
- /// <summary>
- /// Creates an alpha texture of the specified type.
- /// </summary>
- /// <param name="textureType">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.</param>
- /// <param name="textureBounds">Specifies the bounding rectangle of the texture, which can be different than
- /// the bounding rectangle returned by GetAlphaTextureBounds.</param>
- /// <param name="alphaValues">Receives the array of alpha values.</param>
- /// <param name="bufferSize">Size of the alphaValues array. The minimum size depends on the dimensions of the
- /// rectangle and the type of texture requested.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(CreateAlphaTexture)(
- DWRITE_TEXTURE_TYPE textureType,
- __in RECT const* textureBounds,
- __out_bcount(bufferSize) BYTE* alphaValues,
- UINT32 bufferSize
- ) PURE;
-
- /// <summary>
- /// Gets properties required for ClearType blending.
- /// </summary>
- /// <param name="renderingParams">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.</param>
- /// <param name="blendGamma">Receives the gamma value to use for gamma correction.</param>
- /// <param name="blendEnhancedContrast">Receives the enhanced contrast value.</param>
- /// <param name="blendClearTypeLevel">Receives the ClearType level.</param>
- STDMETHOD(GetAlphaBlendParams)(
- IDWriteRenderingParams* renderingParams,
- __out FLOAT* blendGamma,
- __out FLOAT* blendEnhancedContrast,
- __out FLOAT* blendClearTypeLevel
- ) PURE;
-};
-
-/// <summary>
-/// The root factory interface for all DWrite objects.
-/// </summary>
-interface DWRITE_DECLARE_INTERFACE("b859ee5a-d838-4b5b-a2e8-1adc7d93db48") IDWriteFactory : public IUnknown
-{
- /// <summary>
- /// Gets a font collection representing the set of installed fonts.
- /// </summary>
- /// <param name="fontCollection">Receives a pointer to the system font collection object, or NULL in case of failure.</param>
- /// <param name="checkForUpdates">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.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetSystemFontCollection)(
- __out IDWriteFontCollection** fontCollection,
- BOOL checkForUpdates = FALSE
- ) PURE;
-
- /// <summary>
- /// Creates a font collection using a custom font collection loader.
- /// </summary>
- /// <param name="collectionLoader">Application-defined font collection loader, which must have been previously
- /// registered using RegisterFontCollectionLoader.</param>
- /// <param name="collectionKey">Key used by the loader to identify a collection of font files.</param>
- /// <param name="collectionKeySize">Size in bytes of the collection key.</param>
- /// <param name="fontCollection">Receives a pointer to the system font collection object, or NULL in case of failure.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(CreateCustomFontCollection)(
- IDWriteFontCollectionLoader* collectionLoader,
- __in_bcount(collectionKeySize) void const* collectionKey,
- UINT32 collectionKeySize,
- __out IDWriteFontCollection** fontCollection
- ) PURE;
-
- /// <summary>
- /// Registers a custom font collection loader with the factory object.
- /// </summary>
- /// <param name="fontCollectionLoader">Application-defined font collection loader.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(RegisterFontCollectionLoader)(
- IDWriteFontCollectionLoader* fontCollectionLoader
- ) PURE;
-
- /// <summary>
- /// Unregisters a custom font collection loader that was previously registered using RegisterFontCollectionLoader.
- /// </summary>
- /// <param name="fontCollectionLoader">Application-defined font collection loader.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(UnregisterFontCollectionLoader)(
- IDWriteFontCollectionLoader* fontCollectionLoader
- ) PURE;
-
- /// <summary>
- /// CreateFontFileReference creates a font file reference object from a local font file.
- /// </summary>
- /// <param name="filePath">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.</param>
- /// <param name="lastWriteTime">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.</param>
- /// <param name="fontFile">Contains newly created font file reference object, or NULL in case of failure.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(CreateFontFileReference)(
- __in_z WCHAR const* filePath,
- __in_opt FILETIME const* lastWriteTime,
- __out IDWriteFontFile** fontFile
- ) PURE;
-
- /// <summary>
- /// 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.
- /// </summary>
- /// <param name="fontFileReferenceKey">Font file reference key that uniquely identifies the font file resource
- /// during the lifetime of fontFileLoader.</param>
- /// <param name="fontFileReferenceKeySize">Size of font file reference key in bytes.</param>
- /// <param name="fontFileLoader">Font file loader that will be used by the font system to load data from the file identified by
- /// fontFileReferenceKey.</param>
- /// <param name="fontFile">Contains the newly created font file object, or NULL in case of failure.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- /// <remarks>
- /// 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.
- /// </remarks>
- STDMETHOD(CreateCustomFontFileReference)(
- __in_bcount(fontFileReferenceKeySize) void const* fontFileReferenceKey,
- UINT32 fontFileReferenceKeySize,
- IDWriteFontFileLoader* fontFileLoader,
- __out IDWriteFontFile** fontFile
- ) PURE;
-
- /// <summary>
- /// Creates a font face object.
- /// </summary>
- /// <param name="fontFaceType">The file format of the font face.</param>
- /// <param name="numberOfFiles">The number of font files require to represent the font face.</param>
- /// <param name="fontFiles">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.</param>
- /// <param name="faceIndex">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.</param>
- /// <param name="fontFaceSimulationFlags">Font face simulation flags for algorithmic emboldening and italicization.</param>
- /// <param name="fontFace">Contains the newly created font face object, or NULL in case of failure.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- 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;
-
- /// <summary>
- /// Creates a rendering parameters object with default settings for the primary monitor.
- /// </summary>
- /// <param name="renderingParams">Holds the newly created rendering parameters object, or NULL in case of failure.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(CreateRenderingParams)(
- __out IDWriteRenderingParams** renderingParams
- ) PURE;
-
- /// <summary>
- /// Creates a rendering parameters object with default settings for the specified monitor.
- /// </summary>
- /// <param name="monitor">The monitor to read the default values from.</param>
- /// <param name="renderingParams">Holds the newly created rendering parameters object, or NULL in case of failure.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(CreateMonitorRenderingParams)(
- HMONITOR monitor,
- __out IDWriteRenderingParams** renderingParams
- ) PURE;
-
- /// <summary>
- /// Creates a rendering parameters object with the specified properties.
- /// </summary>
- /// <param name="gamma">The gamma value used for gamma correction, which must be greater than zero and cannot exceed 256.</param>
- /// <param name="enhancedContrast">The amount of contrast enhancement, zero or greater.</param>
- /// <param name="clearTypeLevel">The degree of ClearType level, from 0.0f (no ClearType) to 1.0f (full ClearType).</param>
- /// <param name="pixelGeometry">The geometry of a device pixel.</param>
- /// <param name="renderingMode">Method of rendering glyphs. In most cases, this should be DWRITE_RENDERING_MODE_DEFAULT to automatically use an appropriate mode.</param>
- /// <param name="renderingParams">Holds the newly created rendering parameters object, or NULL in case of failure.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(CreateCustomRenderingParams)(
- FLOAT gamma,
- FLOAT enhancedContrast,
- FLOAT clearTypeLevel,
- DWRITE_PIXEL_GEOMETRY pixelGeometry,
- DWRITE_RENDERING_MODE renderingMode,
- __out IDWriteRenderingParams** renderingParams
- ) PURE;
-
- /// <summary>
- /// Registers a font file loader with DirectWrite.
- /// </summary>
- /// <param name="fontFileLoader">Pointer to the implementation of the IDWriteFontFileLoader for a particular file resource type.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- /// <remarks>
- /// 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.
- /// </remarks>
- STDMETHOD(RegisterFontFileLoader)(
- IDWriteFontFileLoader* fontFileLoader
- ) PURE;
-
- /// <summary>
- /// Unregisters a font file loader that was previously registered with the DirectWrite font system using RegisterFontFileLoader.
- /// </summary>
- /// <param name="fontFileLoader">Pointer to the file loader that was previously registered with the DirectWrite font system using RegisterFontFileLoader.</param>
- /// <returns>
- /// 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.
- /// </returns>
- /// <remarks>
- /// 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.
- /// </remarks>
- STDMETHOD(UnregisterFontFileLoader)(
- IDWriteFontFileLoader* fontFileLoader
- ) PURE;
-
- /// <summary>
- /// Create a text format object used for text layout.
- /// </summary>
- /// <param name="fontFamilyName">Name of the font family</param>
- /// <param name="fontCollection">Font collection. NULL indicates the system font collection.</param>
- /// <param name="fontWeight">Font weight</param>
- /// <param name="fontStyle">Font style</param>
- /// <param name="fontStretch">Font stretch</param>
- /// <param name="fontSize">Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.</param>
- /// <param name="localeName">Locale name</param>
- /// <param name="textFormat">Contains newly created text format object, or NULL in case of failure.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- 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;
-
- /// <summary>
- /// Create a typography object used in conjunction with text format for text layout.
- /// </summary>
- /// <param name="typography">Contains newly created typography object, or NULL in case of failure.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(CreateTypography)(
- __out IDWriteTypography** typography
- ) PURE;
-
- /// <summary>
- /// Create an object used for interoperability with GDI.
- /// </summary>
- /// <param name="gdiInterop">Receives the GDI interop object if successful, or NULL in case of failure.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(GetGdiInterop)(
- __out IDWriteGdiInterop** gdiInterop
- ) PURE;
-
- /// <summary>
- /// CreateTextLayout takes a string, format, and associated constraints
- /// and produces and object representing the fully analyzed
- /// and formatted result.
- /// </summary>
- /// <param name="string">The string to layout.</param>
- /// <param name="stringLength">The length of the string.</param>
- /// <param name="textFormat">The format to apply to the string.</param>
- /// <param name="maxWidth">Width of the layout box.</param>
- /// <param name="maxHeight">Height of the layout box.</param>
- /// <param name="textLayout">The resultant object.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(CreateTextLayout)(
- __in_ecount(stringLength) WCHAR const* string,
- UINT32 stringLength,
- IDWriteTextFormat* textFormat,
- FLOAT maxWidth,
- FLOAT maxHeight,
- __out IDWriteTextLayout** textLayout
- ) PURE;
-
- /// <summary>
- /// 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.
- /// </summary>
- /// <param name="string">The string to layout.</param>
- /// <param name="stringLength">The length of the string.</param>
- /// <param name="textFormat">The format to apply to the string.</param>
- /// <param name="layoutWidth">Width of the layout box.</param>
- /// <param name="layoutHeight">Height of the layout box.</param>
- /// <param name="pixelsPerDip">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.</param>
- /// <param name="transform">Optional transform applied to the glyphs and their positions. This transform is applied after the
- /// scaling specified the font size and pixelsPerDip.</param>
- /// <param name="useGdiNatural">
- /// 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.
- /// </param>
- /// <param name="textLayout">The resultant object.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- 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;
-
- /// <summary>
- /// 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.
- /// </summary>
- /// <param name="textFormat">Text format used as a template for the omission sign.</param>
- /// <param name="trimmingSign">Created omission sign.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(CreateEllipsisTrimmingSign)(
- IDWriteTextFormat* textFormat,
- __out IDWriteInlineObject** trimmingSign
- ) PURE;
-
- /// <summary>
- /// Return an interface to perform text analysis with.
- /// </summary>
- /// <param name="textAnalyzer">The resultant object.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- STDMETHOD(CreateTextAnalyzer)(
- __out IDWriteTextAnalyzer** textAnalyzer
- ) PURE;
-
- /// <summary>
- /// 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).
- /// </summary>
- /// <param name="substitutionMethod">Method of number substitution to use.</param>
- /// <param name="localeName">Which locale to obtain the digits from.</param>
- /// <param name="ignoreUserOverride">Ignore the user's settings and use the locale defaults</param>
- /// <param name="numberSubstitution">Receives a pointer to the newly created object.</param>
- STDMETHOD(CreateNumberSubstitution)(
- __in DWRITE_NUMBER_SUBSTITUTION_METHOD substitutionMethod,
- __in_z WCHAR const* localeName,
- __in BOOL ignoreUserOverride,
- __out IDWriteNumberSubstitution** numberSubstitution
- ) PURE;
-
- /// <summary>
- /// Creates a glyph run analysis object, which encapsulates information
- /// used to render a glyph run.
- /// </summary>
- /// <param name="glyphRun">Structure specifying the properties of the glyph run.</param>
- /// <param name="pixelsPerDip">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.</param>
- /// <param name="transform">Optional transform applied to the glyphs and their positions. This transform is applied after the
- /// scaling specified the emSize and pixelsPerDip.</param>
- /// <param name="renderingMode">Specifies the rendering mode, which must be one of the raster rendering modes (i.e., not default
- /// and not outline).</param>
- /// <param name="measuringMode">Specifies the method to measure glyphs.</param>
- /// <param name="baselineOriginX">Horizontal position of the baseline origin, in DIPs.</param>
- /// <param name="baselineOriginY">Vertical position of the baseline origin, in DIPs.</param>
- /// <param name="glyphRunAnalysis">Receives a pointer to the newly created object.</param>
- /// <returns>
- /// Standard HRESULT error code.
- /// </returns>
- 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
-
-/// <summary>
-/// Creates a DirectWrite factory object that is used for subsequent creation of individual DirectWrite objects.
-/// </summary>
-/// <param name="factoryType">Identifies whether the factory object will be shared or isolated.</param>
-/// <param name="iid">Identifies the DirectWrite factory interface, such as __uuidof(IDWriteFactory).</param>
-/// <param name="factory">Receives the DirectWrite factory object.</param>
-/// <returns>
-/// Standard HRESULT error code.
-/// </returns>
-/// <remarks>
-/// 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.
-/// </remarks>
-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)
-
-/// <summary>
-/// Indicates an error in an input file such as a font file.
-/// </summary>
-#define DWRITE_E_FILEFORMAT MAKE_DWRITE_HR_ERR(0x000)
-
-/// <summary>
-/// Indicates an error originating in DirectWrite code, which is not expected to occur but is safe to recover from.
-/// </summary>
-#define DWRITE_E_UNEXPECTED MAKE_DWRITE_HR_ERR(0x001)
-
-/// <summary>
-/// Indicates the specified font does not exist.
-/// </summary>
-#define DWRITE_E_NOFONT MAKE_DWRITE_HR_ERR(0x002)
-
-/// <summary>
-/// A font file could not be opened because the file, directory, network location, drive, or other storage
-/// location does not exist or is unavailable.
-/// </summary>
-#define DWRITE_E_FILENOTFOUND MAKE_DWRITE_HR_ERR(0x003)
-
-/// <summary>
-/// A font file exists but could not be opened due to access denied, sharing violation, or similar error.
-/// </summary>
-#define DWRITE_E_FILEACCESS MAKE_DWRITE_HR_ERR(0x004)
-
-/// <summary>
-/// A font collection is obsolete due to changes in the system.
-/// </summary>
-#define DWRITE_E_FONTCOLLECTIONOBSOLETE MAKE_DWRITE_HR_ERR(0x005)
-
-/// <summary>
-/// The given interface is already registered.
-/// </summary>
-#define DWRITE_E_ALREADYREGISTERED MAKE_DWRITE_HR_ERR(0x006)
-
-#endif /* DWRITE_H_INCLUDED */
+//+-------------------------------------------------------------------------- +// +// 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 + +/// <summary> +/// 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. +/// </summary> +enum DWRITE_FONT_FILE_TYPE +{ + /// <summary> + /// Font type is not recognized by the DirectWrite font system. + /// </summary> + DWRITE_FONT_FILE_TYPE_UNKNOWN, + + /// <summary> + /// OpenType font with CFF outlines. + /// </summary> + DWRITE_FONT_FILE_TYPE_CFF, + + /// <summary> + /// OpenType font with TrueType outlines. + /// </summary> + DWRITE_FONT_FILE_TYPE_TRUETYPE, + + /// <summary> + /// OpenType font that contains a TrueType collection. + /// </summary> + DWRITE_FONT_FILE_TYPE_TRUETYPE_COLLECTION, + + /// <summary> + /// Type 1 PFM font. + /// </summary> + DWRITE_FONT_FILE_TYPE_TYPE1_PFM, + + /// <summary> + /// Type 1 PFB font. + /// </summary> + DWRITE_FONT_FILE_TYPE_TYPE1_PFB, + + /// <summary> + /// Vector .FON font. + /// </summary> + DWRITE_FONT_FILE_TYPE_VECTOR, + + /// <summary> + /// Bitmap .FON font. + /// </summary> + DWRITE_FONT_FILE_TYPE_BITMAP +}; + +/// <summary> +/// 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. +/// </summary> +enum DWRITE_FONT_FACE_TYPE +{ + /// <summary> + /// OpenType font face with CFF outlines. + /// </summary> + DWRITE_FONT_FACE_TYPE_CFF, + + /// <summary> + /// OpenType font face with TrueType outlines. + /// </summary> + DWRITE_FONT_FACE_TYPE_TRUETYPE, + + /// <summary> + /// OpenType font face that is a part of a TrueType collection. + /// </summary> + DWRITE_FONT_FACE_TYPE_TRUETYPE_COLLECTION, + + /// <summary> + /// A Type 1 font face. + /// </summary> + DWRITE_FONT_FACE_TYPE_TYPE1, + + /// <summary> + /// A vector .FON format font face. + /// </summary> + DWRITE_FONT_FACE_TYPE_VECTOR, + + /// <summary> + /// A bitmap .FON format font face. + /// </summary> + DWRITE_FONT_FACE_TYPE_BITMAP, + + /// <summary> + /// Font face type is not recognized by the DirectWrite font system. + /// </summary> + DWRITE_FONT_FACE_TYPE_UNKNOWN +}; + +/// <summary> +/// Specifies algorithmic style simulations to be applied to the font face. +/// Bold and oblique simulations can be combined via bitwise OR operation. +/// </summary> +enum DWRITE_FONT_SIMULATIONS +{ + /// <summary> + /// No simulations are performed. + /// </summary> + DWRITE_FONT_SIMULATIONS_NONE = 0x0000, + + /// <summary> + /// Algorithmic emboldening is performed. + /// </summary> + DWRITE_FONT_SIMULATIONS_BOLD = 0x0001, + + /// <summary> + /// Algorithmic italicization is performed. + /// </summary> + DWRITE_FONT_SIMULATIONS_OBLIQUE = 0x0002 +}; + +#ifdef DEFINE_ENUM_FLAG_OPERATORS +DEFINE_ENUM_FLAG_OPERATORS(DWRITE_FONT_SIMULATIONS); +#endif + +/// <summary> +/// 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. +/// </summary> +enum DWRITE_FONT_WEIGHT +{ + /// <summary> + /// Predefined font weight : Thin (100). + /// </summary> + DWRITE_FONT_WEIGHT_THIN = 100, + + /// <summary> + /// Predefined font weight : Extra-light (200). + /// </summary> + DWRITE_FONT_WEIGHT_EXTRA_LIGHT = 200, + + /// <summary> + /// Predefined font weight : Ultra-light (200). + /// </summary> + DWRITE_FONT_WEIGHT_ULTRA_LIGHT = 200, + + /// <summary> + /// Predefined font weight : Light (300). + /// </summary> + DWRITE_FONT_WEIGHT_LIGHT = 300, + + /// <summary> + /// Predefined font weight : Normal (400). + /// </summary> + DWRITE_FONT_WEIGHT_NORMAL = 400, + + /// <summary> + /// Predefined font weight : Regular (400). + /// </summary> + DWRITE_FONT_WEIGHT_REGULAR = 400, + + /// <summary> + /// Predefined font weight : Medium (500). + /// </summary> + DWRITE_FONT_WEIGHT_MEDIUM = 500, + + /// <summary> + /// Predefined font weight : Demi-bold (600). + /// </summary> + DWRITE_FONT_WEIGHT_DEMI_BOLD = 600, + + /// <summary> + /// Predefined font weight : Semi-bold (600). + /// </summary> + DWRITE_FONT_WEIGHT_SEMI_BOLD = 600, + + /// <summary> + /// Predefined font weight : Bold (700). + /// </summary> + DWRITE_FONT_WEIGHT_BOLD = 700, + + /// <summary> + /// Predefined font weight : Extra-bold (800). + /// </summary> + DWRITE_FONT_WEIGHT_EXTRA_BOLD = 800, + + /// <summary> + /// Predefined font weight : Ultra-bold (800). + /// </summary> + DWRITE_FONT_WEIGHT_ULTRA_BOLD = 800, + + /// <summary> + /// Predefined font weight : Black (900). + /// </summary> + DWRITE_FONT_WEIGHT_BLACK = 900, + + /// <summary> + /// Predefined font weight : Heavy (900). + /// </summary> + DWRITE_FONT_WEIGHT_HEAVY = 900, + + /// <summary> + /// Predefined font weight : Extra-black (950). + /// </summary> + DWRITE_FONT_WEIGHT_EXTRA_BLACK = 950, + + /// <summary> + /// Predefined font weight : Ultra-black (950). + /// </summary> + DWRITE_FONT_WEIGHT_ULTRA_BLACK = 950 +}; + +/// <summary> +/// 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. +/// </summary> +enum DWRITE_FONT_STRETCH +{ + /// <summary> + /// Predefined font stretch : Not known (0). + /// </summary> + DWRITE_FONT_STRETCH_UNDEFINED = 0, + + /// <summary> + /// Predefined font stretch : Ultra-condensed (1). + /// </summary> + DWRITE_FONT_STRETCH_ULTRA_CONDENSED = 1, + + /// <summary> + /// Predefined font stretch : Extra-condensed (2). + /// </summary> + DWRITE_FONT_STRETCH_EXTRA_CONDENSED = 2, + + /// <summary> + /// Predefined font stretch : Condensed (3). + /// </summary> + DWRITE_FONT_STRETCH_CONDENSED = 3, + + /// <summary> + /// Predefined font stretch : Semi-condensed (4). + /// </summary> + DWRITE_FONT_STRETCH_SEMI_CONDENSED = 4, + + /// <summary> + /// Predefined font stretch : Normal (5). + /// </summary> + DWRITE_FONT_STRETCH_NORMAL = 5, + + /// <summary> + /// Predefined font stretch : Medium (5). + /// </summary> + DWRITE_FONT_STRETCH_MEDIUM = 5, + + /// <summary> + /// Predefined font stretch : Semi-expanded (6). + /// </summary> + DWRITE_FONT_STRETCH_SEMI_EXPANDED = 6, + + /// <summary> + /// Predefined font stretch : Expanded (7). + /// </summary> + DWRITE_FONT_STRETCH_EXPANDED = 7, + + /// <summary> + /// Predefined font stretch : Extra-expanded (8). + /// </summary> + DWRITE_FONT_STRETCH_EXTRA_EXPANDED = 8, + + /// <summary> + /// Predefined font stretch : Ultra-expanded (9). + /// </summary> + DWRITE_FONT_STRETCH_ULTRA_EXPANDED = 9 +}; + +/// <summary> +/// 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. +/// </summary> +enum DWRITE_FONT_STYLE +{ + /// <summary> + /// Font slope style : Normal. + /// </summary> + DWRITE_FONT_STYLE_NORMAL, + + /// <summary> + /// Font slope style : Oblique. + /// </summary> + DWRITE_FONT_STYLE_OBLIQUE, + + /// <summary> + /// Font slope style : Italic. + /// </summary> + DWRITE_FONT_STYLE_ITALIC + +}; + +/// <summary> +/// The informational string enumeration identifies a string in a font. +/// </summary> +enum DWRITE_INFORMATIONAL_STRING_ID +{ + /// <summary> + /// Unspecified name ID. + /// </summary> + DWRITE_INFORMATIONAL_STRING_NONE, + + /// <summary> + /// Copyright notice provided by the font. + /// </summary> + DWRITE_INFORMATIONAL_STRING_COPYRIGHT_NOTICE, + + /// <summary> + /// String containing a version number. + /// </summary> + DWRITE_INFORMATIONAL_STRING_VERSION_STRINGS, + + /// <summary> + /// Trademark information provided by the font. + /// </summary> + DWRITE_INFORMATIONAL_STRING_TRADEMARK, + + /// <summary> + /// Name of the font manufacturer. + /// </summary> + DWRITE_INFORMATIONAL_STRING_MANUFACTURER, + + /// <summary> + /// Name of the font designer. + /// </summary> + DWRITE_INFORMATIONAL_STRING_DESIGNER, + + /// <summary> + /// URL of font designer (with protocol, e.g., http://, ftp://). + /// </summary> + DWRITE_INFORMATIONAL_STRING_DESIGNER_URL, + + /// <summary> + /// Description of the font. Can contain revision information, usage recommendations, history, features, etc. + /// </summary> + DWRITE_INFORMATIONAL_STRING_DESCRIPTION, + + /// <summary> + /// 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. + /// </summary> + DWRITE_INFORMATIONAL_STRING_FONT_VENDOR_URL, + + /// <summary> + /// 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. + /// </summary> + DWRITE_INFORMATIONAL_STRING_LICENSE_DESCRIPTION, + + /// <summary> + /// URL where additional licensing information can be found. + /// </summary> + DWRITE_INFORMATIONAL_STRING_LICENSE_INFO_URL, + + /// <summary> + /// 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"). + /// </summary> + DWRITE_INFORMATIONAL_STRING_WIN32_FAMILY_NAMES, + + /// <summary> + /// GDI-compatible subfamily name. + /// </summary> + DWRITE_INFORMATIONAL_STRING_WIN32_SUBFAMILY_NAMES, + + /// <summary> + /// 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. + /// </summary> + DWRITE_INFORMATIONAL_STRING_PREFERRED_FAMILY_NAMES, + + /// <summary> + /// Subfamily name preferred by the designer. This name is typically only present if it differs from the GDI-compatible subfamily name. + /// </summary> + DWRITE_INFORMATIONAL_STRING_PREFERRED_SUBFAMILY_NAMES, + + /// <summary> + /// 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. + /// </summary> + DWRITE_INFORMATIONAL_STRING_SAMPLE_TEXT +}; + + +/// <summary> +/// The DWRITE_FONT_METRICS structure specifies the metrics of a font face that +/// are applicable to all glyphs within the font face. +/// </summary> +struct DWRITE_FONT_METRICS +{ + /// <summary> + /// 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. + /// </summary> + UINT16 designUnitsPerEm; + + /// <summary> + /// 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. + /// </summary> + UINT16 ascent; + + /// <summary> + /// 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. + /// </summary> + UINT16 descent; + + /// <summary> + /// 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. + /// </summary> + INT16 lineGap; + + /// <summary> + /// 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. + /// </summary> + UINT16 capHeight; + + /// <summary> + /// 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. + /// </summary> + UINT16 xHeight; + + /// <summary> + /// 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. + /// </summary> + INT16 underlinePosition; + + /// <summary> + /// The suggested underline thickness value of the font face in font design units. + /// </summary> + UINT16 underlineThickness; + + /// <summary> + /// 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. + /// </summary> + INT16 strikethroughPosition; + + /// <summary> + /// The suggested strikethrough thickness value of the font face in font design units. + /// </summary> + UINT16 strikethroughThickness; +}; + +/// <summary> +/// The DWRITE_GLYPH_METRICS structure specifies the metrics of an individual glyph. +/// The units depend on how the metrics are obtained. +/// </summary> +struct DWRITE_GLYPH_METRICS +{ + /// <summary> + /// 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'). + /// </summary> + INT32 leftSideBearing; + + /// <summary> + /// Specifies the X offset from the origin of the current glyph to the origin of the next glyph when writing horizontally. + /// </summary> + UINT32 advanceWidth; + + /// <summary> + /// 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. + /// </summary> + INT32 rightSideBearing; + + /// <summary> + /// 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. + /// </summary> + INT32 topSideBearing; + + /// <summary> + /// 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). + /// </summary> + UINT32 advanceHeight; + + /// <summary> + /// 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. + /// </summary> + INT32 bottomSideBearing; + + /// <summary> + /// 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. + /// </summary> + INT32 verticalOriginY; +}; + +/// <summary> +/// 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. +/// </summary> +struct DWRITE_GLYPH_OFFSET +{ + /// <summary> + /// 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. + /// </summary> + FLOAT advanceOffset; + + /// <summary> + /// Offset in the ascent direction, i.e., the direction ascenders point. A positive ascender offset moves + /// the glyph up (in pre-transform coordinates). + /// </summary> + FLOAT ascenderOffset; +}; + +/// <summary> +/// 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. +/// </summary> +enum DWRITE_FACTORY_TYPE +{ + /// <summary> + /// 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. + /// </summary> + DWRITE_FACTORY_TYPE_SHARED, + + /// <summary> + /// Objects created from the isolated factory do not interact with internal DirectWrite state from other components. + /// </summary> + 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<UINT32>(static_cast<UINT8>(d)) << 24) | \ + (static_cast<UINT32>(static_cast<UINT8>(c)) << 16) | \ + (static_cast<UINT32>(static_cast<UINT8>(b)) << 8) | \ + static_cast<UINT32>(static_cast<UINT8>(a))) + +interface IDWriteFontFileStream; + +/// <summary> +/// 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. +/// </summary> +interface DWRITE_DECLARE_INTERFACE("727cad4e-d6af-4c9e-8a08-d695b11caa49") IDWriteFontFileLoader : public IUnknown +{ + /// <summary> + /// Creates a font file stream object that encapsulates an open file resource. + /// The resource is closed when the last reference to fontFileStream is released. + /// </summary> + /// <param name="fontFileReferenceKey">Font file reference key that uniquely identifies the font file resource + /// within the scope of the font loader being used.</param> + /// <param name="fontFileReferenceKeySize">Size of font file reference key in bytes.</param> + /// <param name="fontFileStream">Pointer to the newly created font file stream.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(CreateStreamFromKey)( + __in_bcount(fontFileReferenceKeySize) void const* fontFileReferenceKey, + UINT32 fontFileReferenceKeySize, + __out IDWriteFontFileStream** fontFileStream + ) PURE; +}; + +/// <summary> +/// 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. +/// </summary> +interface DWRITE_DECLARE_INTERFACE("b2d9f3ec-c9fe-4a11-a2ec-d86208f7c0a2") IDWriteLocalFontFileLoader : public IDWriteFontFileLoader +{ + /// <summary> + /// Obtains the length of the absolute file path from the font file reference key. + /// </summary> + /// <param name="fontFileReferenceKey">Font file reference key that uniquely identifies the local font file + /// within the scope of the font loader being used.</param> + /// <param name="fontFileReferenceKeySize">Size of font file reference key in bytes.</param> + /// <param name="filePathLength">Length of the file path string not including the terminated NULL character.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetFilePathLengthFromKey)( + __in_bcount(fontFileReferenceKeySize) void const* fontFileReferenceKey, + UINT32 fontFileReferenceKeySize, + __out UINT32* filePathLength + ) PURE; + + /// <summary> + /// Obtains the absolute font file path from the font file reference key. + /// </summary> + /// <param name="fontFileReferenceKey">Font file reference key that uniquely identifies the local font file + /// within the scope of the font loader being used.</param> + /// <param name="fontFileReferenceKeySize">Size of font file reference key in bytes.</param> + /// <param name="filePath">Character array that receives the local file path.</param> + /// <param name="filePathSize">Size of the filePath array in character count including the terminated NULL character.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetFilePathFromKey)( + __in_bcount(fontFileReferenceKeySize) void const* fontFileReferenceKey, + UINT32 fontFileReferenceKeySize, + __out_ecount_z(filePathSize) WCHAR* filePath, + UINT32 filePathSize + ) PURE; + + /// <summary> + /// Obtains the last write time of the file from the font file reference key. + /// </summary> + /// <param name="fontFileReferenceKey">Font file reference key that uniquely identifies the local font file + /// within the scope of the font loader being used.</param> + /// <param name="fontFileReferenceKeySize">Size of font file reference key in bytes.</param> + /// <param name="lastWriteTime">Last modified time of the font file.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetLastWriteTimeFromKey)( + __in_bcount(fontFileReferenceKeySize) void const* fontFileReferenceKey, + UINT32 fontFileReferenceKeySize, + __out FILETIME* lastWriteTime + ) PURE; +}; + +/// <summary> +/// The interface for loading font file data. +/// </summary> +interface DWRITE_DECLARE_INTERFACE("6d4865fe-0ab8-4d91-8f62-5dd6be34a3e0") IDWriteFontFileStream : public IUnknown +{ + /// <summary> + /// Reads a fragment from a file. + /// </summary> + /// <param name="fragmentStart">Receives the pointer to the start of the font file fragment.</param> + /// <param name="fileOffset">Offset of the fragment from the beginning of the font file.</param> + /// <param name="fragmentSize">Size of the fragment in bytes.</param> + /// <param name="fragmentContext">The client defined context to be passed to the ReleaseFileFragment.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + /// <remarks> + /// IMPORTANT: ReadFileFragment() implementations must check whether the requested file fragment + /// is within the file bounds. Otherwise, an error should be returned from ReadFileFragment. + /// </remarks> + STDMETHOD(ReadFileFragment)( + __deref_out_bcount(fragmentSize) void const** fragmentStart, + UINT64 fileOffset, + UINT64 fragmentSize, + __out void** fragmentContext + ) PURE; + + /// <summary> + /// Releases a fragment from a file. + /// </summary> + /// <param name="fragmentContext">The client defined context of a font fragment returned from ReadFileFragment.</param> + STDMETHOD_(void, ReleaseFileFragment)( + void* fragmentContext + ) PURE; + + /// <summary> + /// Obtains the total size of a file. + /// </summary> + /// <param name="fileSize">Receives the total size of the file.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + /// <remarks> + /// 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). + /// </remarks> + STDMETHOD(GetFileSize)( + __out UINT64* fileSize + ) PURE; + + /// <summary> + /// 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. + /// </summary> + /// <param name="lastWriteTime">Receives the last modifed time of the file in the format that represents + /// the number of 100-nanosecond intervals since January 1, 1601 (UTC).</param> + /// <returns> + /// 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. + /// </returns> + STDMETHOD(GetLastWriteTime)( + __out UINT64* lastWriteTime + ) PURE; +}; + +/// <summary> +/// The interface that represents a reference to a font file. +/// </summary> +interface DWRITE_DECLARE_INTERFACE("739d886a-cef5-47dc-8769-1a8b41bebbb0") IDWriteFontFile : public IUnknown +{ + /// <summary> + /// 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. + /// </summary> + /// <param name="fontFileReferenceKey">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.</param> + /// <param name="fontFileReferenceKeySize">Size of font file reference key in bytes.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetReferenceKey)( + __deref_out_bcount(*fontFileReferenceKeySize) void const** fontFileReferenceKey, + __out UINT32* fontFileReferenceKeySize + ) PURE; + + /// <summary> + /// Obtains the file loader associated with a font file object. + /// </summary> + /// <param name="fontFileLoader">The font file loader associated with the font file object.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetLoader)( + __out IDWriteFontFileLoader** fontFileLoader + ) PURE; + + /// <summary> + /// Analyzes a file and returns whether it represents a font, and whether the font type is supported by the font system. + /// </summary> + /// <param name="isSupportedFontType">TRUE if the font type is supported by the font system, FALSE otherwise.</param> + /// <param name="fontFileType">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.</param> + /// <param name="fontFaceType">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.</param> + /// <param name="numberOfFaces">Number of font faces contained in the font file.</param> + /// <returns> + /// Standard HRESULT error code if there was a processing error during analysis. + /// </returns> + /// <remarks> + /// 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. + /// </remarks> + STDMETHOD(Analyze)( + __out BOOL* isSupportedFontType, + __out DWRITE_FONT_FILE_TYPE* fontFileType, + __out_opt DWRITE_FONT_FACE_TYPE* fontFaceType, + __out UINT32* numberOfFaces + ) PURE; +}; + +/// <summary> +/// 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. +/// </summary> +#ifndef DWRITE_PIXEL_GEOMETRY_DEFINED +enum DWRITE_PIXEL_GEOMETRY +{ + /// <summary> + /// The red, green, and blue color components of each pixel are assumed to occupy the same point. + /// </summary> + DWRITE_PIXEL_GEOMETRY_FLAT, + + /// <summary> + /// 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. + /// </summary> + DWRITE_PIXEL_GEOMETRY_RGB, + + /// <summary> + /// Each pixel comprises three vertical stripes, with blue on the left, green in the center, and + /// red on the right. + /// </summary> + DWRITE_PIXEL_GEOMETRY_BGR +}; +#define DWRITE_PIXEL_GEOMETRY_DEFINED +#endif + +/// <summary> +/// Represents a method of rendering glyphs. +/// </summary> +enum DWRITE_RENDERING_MODE +{ + /// <summary> + /// Specifies that the rendering mode is determined automatically based on the font and size. + /// </summary> + DWRITE_RENDERING_MODE_DEFAULT, + + /// <summary> + /// 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. + /// </summary> + DWRITE_RENDERING_MODE_ALIASED, + + /// <summary> + /// Specifies ClearType rendering with the same metrics as aliased text. Glyphs can only + /// be positioned on whole-pixel boundaries. + /// </summary> + DWRITE_RENDERING_MODE_CLEARTYPE_GDI_CLASSIC, + + /// <summary> + /// 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. + /// </summary> + DWRITE_RENDERING_MODE_CLEARTYPE_GDI_NATURAL, + + /// <summary> + /// 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). + /// </summary> + DWRITE_RENDERING_MODE_CLEARTYPE_NATURAL, + + /// <summary> + /// 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. + /// </summary> + DWRITE_RENDERING_MODE_CLEARTYPE_NATURAL_SYMMETRIC, + + /// <summary> + /// Specifies that rendering should bypass the rasterizer and use the outlines directly. This is + /// typically used at very large sizes. + /// </summary> + DWRITE_RENDERING_MODE_OUTLINE +}; + +/// <summary> +/// The DWRITE_MATRIX structure specifies the graphics transform to be applied +/// to rendered glyphs. +/// </summary> +struct DWRITE_MATRIX +{ + /// <summary> + /// Horizontal scaling / cosine of rotation + /// </summary> + FLOAT m11; + + /// <summary> + /// Vertical shear / sine of rotation + /// </summary> + FLOAT m12; + + /// <summary> + /// Horizontal shear / negative sine of rotation + /// </summary> + FLOAT m21; + + /// <summary> + /// Vertical scaling / cosine of rotation + /// </summary> + FLOAT m22; + + /// <summary> + /// Horizontal shift (always orthogonal regardless of rotation) + /// </summary> + FLOAT dx; + + /// <summary> + /// Vertical shift (always orthogonal regardless of rotation) + /// </summary> + FLOAT dy; +}; + +/// <summary> +/// The interface that represents text rendering settings for glyph rasterization and filtering. +/// </summary> +interface DWRITE_DECLARE_INTERFACE("2f0da53a-2add-47cd-82ee-d9ec34688e75") IDWriteRenderingParams : public IUnknown +{ + /// <summary> + /// Gets the gamma value used for gamma correction. Valid values must be + /// greater than zero and cannot exceed 256. + /// </summary> + STDMETHOD_(FLOAT, GetGamma)() PURE; + + /// <summary> + /// Gets the amount of contrast enhancement. Valid values are greater than + /// or equal to zero. + /// </summary> + STDMETHOD_(FLOAT, GetEnhancedContrast)() PURE; + + /// <summary> + /// Gets the ClearType level. Valid values range from 0.0f (no ClearType) + /// to 1.0f (full ClearType). + /// </summary> + STDMETHOD_(FLOAT, GetClearTypeLevel)() PURE; + + /// <summary> + /// Gets the pixel geometry. + /// </summary> + STDMETHOD_(DWRITE_PIXEL_GEOMETRY, GetPixelGeometry)() PURE; + + /// <summary> + /// Gets the rendering mode. + /// </summary> + STDMETHOD_(DWRITE_RENDERING_MODE, GetRenderingMode)() PURE; +}; + +// Forward declarations of D2D types +interface ID2D1SimplifiedGeometrySink; + +typedef ID2D1SimplifiedGeometrySink IDWriteGeometrySink; + +/// <summary> +/// 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. +/// </summary> +interface DWRITE_DECLARE_INTERFACE("5f49804d-7024-4d43-bfa9-d25984f53849") IDWriteFontFace : public IUnknown +{ + /// <summary> + /// Obtains the file format type of a font face. + /// </summary> + STDMETHOD_(DWRITE_FONT_FACE_TYPE, GetType)() PURE; + + /// <summary> + /// Obtains the font files representing a font face. + /// </summary> + /// <param name="numberOfFiles">The number of files representing the font face.</param> + /// <param name="fontFiles">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.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetFiles)( + __inout UINT32* numberOfFiles, + __out_ecount_opt(*numberOfFiles) IDWriteFontFile** fontFiles + ) PURE; + + /// <summary> + /// 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. + /// </summary> + STDMETHOD_(UINT32, GetIndex)() PURE; + + /// <summary> + /// Obtains the algorithmic style simulation flags of a font face. + /// </summary> + STDMETHOD_(DWRITE_FONT_SIMULATIONS, GetSimulations)() PURE; + + /// <summary> + /// Determines whether the font is a symbol font. + /// </summary> + STDMETHOD_(BOOL, IsSymbolFont)() PURE; + + /// <summary> + /// 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. + /// </summary> + /// <param name="fontFaceMetrics">Points to a DWRITE_FONT_METRICS structure to fill in. + /// The metrics returned by this function are in font design units.</param> + STDMETHOD_(void, GetMetrics)( + __out DWRITE_FONT_METRICS* fontFaceMetrics + ) PURE; + + /// <summary> + /// Obtains the number of glyphs in the font face. + /// </summary> + STDMETHOD_(UINT16, GetGlyphCount)() PURE; + + /// <summary> + /// Obtains ideal glyph metrics in font design units. Design glyphs metrics are used for glyph positioning. + /// </summary> + /// <param name="glyphIndices">An array of glyph indices to compute the metrics for.</param> + /// <param name="glyphCount">The number of elements in the glyphIndices array.</param> + /// <param name="glyphMetrics">Array of DWRITE_GLYPH_METRICS structures filled by this function. + /// The metrics returned by this function are in font design units.</param> + /// <param name="isSideways">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.</param> + /// <returns> + /// 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. + /// </returns> + STDMETHOD(GetDesignGlyphMetrics)( + __in_ecount(glyphCount) UINT16 const* glyphIndices, + UINT32 glyphCount, + __out_ecount(glyphCount) DWRITE_GLYPH_METRICS* glyphMetrics, + BOOL isSideways = FALSE + ) PURE; + + /// <summary> + /// 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. + /// </summary> + /// <param name="codePoints">An array of USC4 code points to obtain nominal glyph indices from.</param> + /// <param name="codePointCount">The number of elements in the codePoints array.</param> + /// <param name="glyphIndices">Array of nominal glyph indices filled by this function.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetGlyphIndices)( + __in_ecount(codePointCount) UINT32 const* codePoints, + UINT32 codePointCount, + __out_ecount(codePointCount) UINT16* glyphIndices + ) PURE; + + /// <summary> + /// 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. + /// </summary> + /// <param name="openTypeTableTag">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.</param> + /// <param name="tableData"> + /// 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). + /// </param> + /// <param name="tableSize">Byte size of table.</param> + /// <param name="tableContext"> + /// 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. + /// </param> + /// <param name="exists">True if table exists.</param> + /// <returns> + /// 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. + /// </returns> + /// <remarks> + /// The context for the same tag may be different for each call, + /// so each one must be held and released separately. + /// </remarks> + STDMETHOD(TryGetFontTable)( + __in UINT32 openTypeTableTag, + __deref_out_bcount(*tableSize) const void** tableData, + __out UINT32* tableSize, + __out void** tableContext, + __out BOOL* exists + ) PURE; + + /// <summary> + /// Releases the table obtained earlier from TryGetFontTable. + /// </summary> + /// <param name="tableContext">Opaque context from TryGetFontTable.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD_(void, ReleaseFontTable)( + __in void* tableContext + ) PURE; + + /// <summary> + /// Computes the outline of a run of glyphs by calling back to the outline sink interface. + /// </summary> + /// <param name="emSize">Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.</param> + /// <param name="glyphIndices">Array of glyph indices.</param> + /// <param name="glyphAdvances">Optional array of glyph advances in DIPs.</param> + /// <param name="glyphOffsets">Optional array of glyph offsets.</param> + /// <param name="glyphCount">Number of glyphs.</param> + /// <param name="isSideways">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.</param> + /// <param name="isRightToLeft">If true, specifies that the advance direction is right to left. By default, the advance direction + /// is left to right.</param> + /// <param name="geometrySink">Interface the function calls back to draw each element of the geometry.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + 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; + + /// <summary> + /// Determines the recommended rendering mode for the font given the specified size and rendering parameters. + /// </summary> + /// <param name="emSize">Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.</param> + /// <param name="pixelsPerDip">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.</param> + /// <param name="measuringMode">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 + /// </param> + /// <param name="renderingParams">Rendering parameters object. This parameter is necessary in case the rendering parameters + /// object overrides the rendering mode.</param> + /// <param name="renderingMode">Receives the recommended rendering mode to use.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetRecommendedRenderingMode)( + FLOAT emSize, + FLOAT pixelsPerDip, + DWRITE_MEASURING_MODE measuringMode, + IDWriteRenderingParams* renderingParams, + __out DWRITE_RENDERING_MODE* renderingMode + ) PURE; + + /// <summary> + /// 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. + /// </summary> + /// <param name="emSize">Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.</param> + /// <param name="pixelsPerDip">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.</param> + /// <param name="transform">Optional transform applied to the glyphs and their positions. This transform is applied after the + /// scaling specified by the font size and pixelsPerDip.</param> + /// <param name="fontFaceMetrics">Points to a DWRITE_FONT_METRICS structure to fill in. + /// The metrics returned by this function are in font design units.</param> + STDMETHOD(GetGdiCompatibleMetrics)( + FLOAT emSize, + FLOAT pixelsPerDip, + __in_opt DWRITE_MATRIX const* transform, + __out DWRITE_FONT_METRICS* fontFaceMetrics + ) PURE; + + + /// <summary> + /// 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. + /// </summary> + /// <param name="emSize">Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.</param> + /// <param name="pixelsPerDip">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.</param> + /// <param name="transform">Optional transform applied to the glyphs and their positions. This transform is applied after the + /// scaling specified by the font size and pixelsPerDip.</param> + /// <param name="useGdiNatural"> + /// 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. + /// </param> + /// <param name="glyphIndices">An array of glyph indices to compute the metrics for.</param> + /// <param name="glyphCount">The number of elements in the glyphIndices array.</param> + /// <param name="glyphMetrics">Array of DWRITE_GLYPH_METRICS structures filled by this function. + /// The metrics returned by this function are in font design units.</param> + /// <param name="isSideways">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.</param> + /// <returns> + /// 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. + /// </returns> + 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; + +/// <summary> +/// 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. +/// </summary> +interface DWRITE_DECLARE_INTERFACE("cca920e4-52f0-492b-bfa8-29c72ee0a468") IDWriteFontCollectionLoader : public IUnknown +{ + /// <summary> + /// 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. + /// </summary> + /// <param name="factory">Factory associated with the loader.</param> + /// <param name="collectionKey">Font collection key that uniquely identifies the collection of font files within + /// the scope of the font collection loader being used.</param> + /// <param name="collectionKeySize">Size of the font collection key in bytes.</param> + /// <param name="fontFileEnumerator">Pointer to the newly created font file enumerator.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(CreateEnumeratorFromKey)( + IDWriteFactory* factory, + __in_bcount(collectionKeySize) void const* collectionKey, + UINT32 collectionKeySize, + __out IDWriteFontFileEnumerator** fontFileEnumerator + ) PURE; +}; + +/// <summary> +/// 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. +/// </summary> +interface DWRITE_DECLARE_INTERFACE("72755049-5ff7-435d-8348-4be97cfa6c7c") IDWriteFontFileEnumerator : public IUnknown +{ + /// <summary> + /// 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. + /// </summary> + /// <param name="hasCurrentFile">Receives the value TRUE if the enumerator advances to a file, or FALSE if + /// the enumerator advanced past the last file in the collection.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(MoveNext)( + __out BOOL* hasCurrentFile + ) PURE; + + /// <summary> + /// Gets a reference to the current font file. + /// </summary> + /// <param name="fontFile">Pointer to the newly created font file object.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetCurrentFontFile)( + __out IDWriteFontFile** fontFile + ) PURE; +}; + +/// <summary> +/// Represents a collection of strings indexed by locale name. +/// </summary> +interface DWRITE_DECLARE_INTERFACE("08256209-099a-4b34-b86d-c22b110e7771") IDWriteLocalizedStrings : public IUnknown +{ + /// <summary> + /// Gets the number of language/string pairs. + /// </summary> + STDMETHOD_(UINT32, GetCount)() PURE; + + /// <summary> + /// Gets the index of the item with the specified locale name. + /// </summary> + /// <param name="localeName">Locale name to look for.</param> + /// <param name="index">Receives the zero-based index of the locale name/string pair.</param> + /// <param name="exists">Receives TRUE if the locale name exists or FALSE if not.</param> + /// <returns> + /// 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. + /// </returns> + STDMETHOD(FindLocaleName)( + __in_z WCHAR const* localeName, + __out UINT32* index, + __out BOOL* exists + ) PURE; + + /// <summary> + /// Gets the length in characters (not including the null terminator) of the locale name with the specified index. + /// </summary> + /// <param name="index">Zero-based index of the locale name.</param> + /// <param name="length">Receives the length in characters, not including the null terminator.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetLocaleNameLength)( + UINT32 index, + __out UINT32* length + ) PURE; + + /// <summary> + /// Copies the locale name with the specified index to the specified array. + /// </summary> + /// <param name="index">Zero-based index of the locale name.</param> + /// <param name="localeName">Character array that receives the locale name.</param> + /// <param name="size">Size of the array in characters. The size must include space for the terminating + /// null character.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetLocaleName)( + UINT32 index, + __out_ecount_z(size) WCHAR* localeName, + UINT32 size + ) PURE; + + /// <summary> + /// Gets the length in characters (not including the null terminator) of the string with the specified index. + /// </summary> + /// <param name="index">Zero-based index of the string.</param> + /// <param name="length">Receives the length in characters, not including the null terminator.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetStringLength)( + UINT32 index, + __out UINT32* length + ) PURE; + + /// <summary> + /// Copies the string with the specified index to the specified array. + /// </summary> + /// <param name="index">Zero-based index of the string.</param> + /// <param name="stringBuffer">Character array that receives the string.</param> + /// <param name="size">Size of the array in characters. The size must include space for the terminating + /// null character.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetString)( + UINT32 index, + __out_ecount_z(size) WCHAR* stringBuffer, + UINT32 size + ) PURE; +}; + +interface IDWriteFontFamily; +interface IDWriteFont; + +/// <summary> +/// The IDWriteFontCollection encapsulates a collection of fonts. +/// </summary> +interface DWRITE_DECLARE_INTERFACE("a84cee02-3eea-4eee-a827-87c1a02a0fcc") IDWriteFontCollection : public IUnknown +{ + /// <summary> + /// Gets the number of font families in the collection. + /// </summary> + STDMETHOD_(UINT32, GetFontFamilyCount)() PURE; + + /// <summary> + /// Creates a font family object given a zero-based font family index. + /// </summary> + /// <param name="index">Zero-based index of the font family.</param> + /// <param name="fontFamily">Receives a pointer the newly created font family object.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetFontFamily)( + UINT32 index, + __out IDWriteFontFamily** fontFamily + ) PURE; + + /// <summary> + /// Finds the font family with the specified family name. + /// </summary> + /// <param name="familyName">Name of the font family. The name is not case-sensitive but must otherwise exactly match a family name in the collection.</param> + /// <param name="index">Receives the zero-based index of the matching font family if the family name was found or UINT_MAX otherwise.</param> + /// <param name="exists">Receives TRUE if the family name exists or FALSE otherwise.</param> + /// <returns> + /// 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. + /// </returns> + STDMETHOD(FindFamilyName)( + __in_z WCHAR const* familyName, + __out UINT32* index, + __out BOOL* exists + ) PURE; + + /// <summary> + /// 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. + /// </summary> + /// <param name="fontFace">Font face object that specifies the physical font.</param> + /// <param name="font">Receives a pointer to the newly created font object if successful or NULL otherwise.</param> + /// <returns> + /// Standard HRESULT error code. If the specified physical font is not part of the font collection the return value is DWRITE_E_NOFONT. + /// </returns> + STDMETHOD(GetFontFromFontFace)( + IDWriteFontFace* fontFace, + __out IDWriteFont** font + ) PURE; +}; + +/// <summary> +/// The IDWriteFontList interface represents a list of fonts. +/// </summary> +interface DWRITE_DECLARE_INTERFACE("1a0d8438-1d97-4ec1-aef9-a2fb86ed6acb") IDWriteFontList : public IUnknown +{ + /// <summary> + /// Gets the font collection that contains the fonts. + /// </summary> + /// <param name="fontCollection">Receives a pointer to the font collection object.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetFontCollection)( + __out IDWriteFontCollection** fontCollection + ) PURE; + + /// <summary> + /// Gets the number of fonts in the font list. + /// </summary> + STDMETHOD_(UINT32, GetFontCount)() PURE; + + /// <summary> + /// Gets a font given its zero-based index. + /// </summary> + /// <param name="index">Zero-based index of the font in the font list.</param> + /// <param name="font">Receives a pointer to the newly created font object.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetFont)( + UINT32 index, + __out IDWriteFont** font + ) PURE; +}; + +/// <summary> +/// The IDWriteFontFamily interface represents a set of fonts that share the same design but are differentiated +/// by weight, stretch, and style. +/// </summary> +interface DWRITE_DECLARE_INTERFACE("da20d8ef-812a-4c43-9802-62ec4abd7add") IDWriteFontFamily : public IDWriteFontList +{ + /// <summary> + /// Creates an localized strings object that contains the family names for the font family, indexed by locale name. + /// </summary> + /// <param name="names">Receives a pointer to the newly created localized strings object.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetFamilyNames)( + __out IDWriteLocalizedStrings** names + ) PURE; + + /// <summary> + /// Gets the font that best matches the specified properties. + /// </summary> + /// <param name="weight">Requested font weight.</param> + /// <param name="stretch">Requested font stretch.</param> + /// <param name="style">Requested font style.</param> + /// <param name="matchingFont">Receives a pointer to the newly created font object.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetFirstMatchingFont)( + DWRITE_FONT_WEIGHT weight, + DWRITE_FONT_STRETCH stretch, + DWRITE_FONT_STYLE style, + __out IDWriteFont** matchingFont + ) PURE; + + /// <summary> + /// Gets a list of fonts in the font family ranked in order of how well they match the specified properties. + /// </summary> + /// <param name="weight">Requested font weight.</param> + /// <param name="stretch">Requested font stretch.</param> + /// <param name="style">Requested font style.</param> + /// <param name="matchingFonts">Receives a pointer to the newly created font list object.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetMatchingFonts)( + DWRITE_FONT_WEIGHT weight, + DWRITE_FONT_STRETCH stretch, + DWRITE_FONT_STYLE style, + __out IDWriteFontList** matchingFonts + ) PURE; +}; + +/// <summary> +/// The IDWriteFont interface represents a physical font in a font collection. +/// </summary> +interface DWRITE_DECLARE_INTERFACE("acd16696-8c14-4f5d-877e-fe3fc1d32737") IDWriteFont : public IUnknown +{ + /// <summary> + /// Gets the font family to which the specified font belongs. + /// </summary> + /// <param name="fontFamily">Receives a pointer to the font family object.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetFontFamily)( + __out IDWriteFontFamily** fontFamily + ) PURE; + + /// <summary> + /// Gets the weight of the specified font. + /// </summary> + STDMETHOD_(DWRITE_FONT_WEIGHT, GetWeight)() PURE; + + /// <summary> + /// Gets the stretch (aka. width) of the specified font. + /// </summary> + STDMETHOD_(DWRITE_FONT_STRETCH, GetStretch)() PURE; + + /// <summary> + /// Gets the style (aka. slope) of the specified font. + /// </summary> + STDMETHOD_(DWRITE_FONT_STYLE, GetStyle)() PURE; + + /// <summary> + /// Returns TRUE if the font is a symbol font or FALSE if not. + /// </summary> + STDMETHOD_(BOOL, IsSymbolFont)() PURE; + + /// <summary> + /// Gets a localized strings collection containing the face names for the font (e.g., Regular or Bold), indexed by locale name. + /// </summary> + /// <param name="names">Receives a pointer to the newly created localized strings object.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetFaceNames)( + __out IDWriteLocalizedStrings** names + ) PURE; + + /// <summary> + /// Gets a localized strings collection containing the specified informational strings, indexed by locale name. + /// </summary> + /// <param name="informationalStringID">Identifies the string to get.</param> + /// <param name="informationalStrings">Receives a pointer to the newly created localized strings object.</param> + /// <param name="exists">Receives the value TRUE if the font contains the specified string ID or FALSE if not.</param> + /// <returns> + /// 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. + /// </returns> + STDMETHOD(GetInformationalStrings)( + DWRITE_INFORMATIONAL_STRING_ID informationalStringID, + __out IDWriteLocalizedStrings** informationalStrings, + __out BOOL* exists + ) PURE; + + /// <summary> + /// Gets a value that indicates what simulation are applied to the specified font. + /// </summary> + STDMETHOD_(DWRITE_FONT_SIMULATIONS, GetSimulations)() PURE; + + /// <summary> + /// Gets the metrics for the font. + /// </summary> + /// <param name="fontMetrics">Receives the font metrics.</param> + STDMETHOD_(void, GetMetrics)( + __out DWRITE_FONT_METRICS* fontMetrics + ) PURE; + + /// <summary> + /// Determines whether the font supports the specified character. + /// </summary> + /// <param name="unicodeValue">Unicode (UCS-4) character value.</param> + /// <param name="exists">Receives the value TRUE if the font supports the specified character or FALSE if not.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(HasCharacter)( + UINT32 unicodeValue, + __out BOOL* exists + ) PURE; + + /// <summary> + /// Creates a font face object for the font. + /// </summary> + /// <param name="fontFace">Receives a pointer to the newly created font face object.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(CreateFontFace)( + __out IDWriteFontFace** fontFace + ) PURE; +}; + +/// <summary> +/// Direction for how reading progresses. +/// </summary> +enum DWRITE_READING_DIRECTION +{ + /// <summary> + /// Reading progresses from left to right. + /// </summary> + DWRITE_READING_DIRECTION_LEFT_TO_RIGHT, + + /// <summary> + /// Reading progresses from right to left. + /// </summary> + DWRITE_READING_DIRECTION_RIGHT_TO_LEFT +}; + +/// <summary> +/// Direction for how lines of text are placed relative to one another. +/// </summary> +enum DWRITE_FLOW_DIRECTION +{ + /// <summary> + /// Text lines are placed from top to bottom. + /// </summary> + DWRITE_FLOW_DIRECTION_TOP_TO_BOTTOM +}; + +/// <summary> +/// Alignment of paragraph text along the reading direction axis relative to +/// the leading and trailing edge of the layout box. +/// </summary> +enum DWRITE_TEXT_ALIGNMENT +{ + /// <summary> + /// The leading edge of the paragraph text is aligned to the layout box's leading edge. + /// </summary> + DWRITE_TEXT_ALIGNMENT_LEADING, + + /// <summary> + /// The trailing edge of the paragraph text is aligned to the layout box's trailing edge. + /// </summary> + DWRITE_TEXT_ALIGNMENT_TRAILING, + + /// <summary> + /// The center of the paragraph text is aligned to the center of the layout box. + /// </summary> + DWRITE_TEXT_ALIGNMENT_CENTER +}; + +/// <summary> +/// Alignment of paragraph text along the flow direction axis relative to the +/// flow's beginning and ending edge of the layout box. +/// </summary> +enum DWRITE_PARAGRAPH_ALIGNMENT +{ + /// <summary> + /// The first line of paragraph is aligned to the flow's beginning edge of the layout box. + /// </summary> + DWRITE_PARAGRAPH_ALIGNMENT_NEAR, + + /// <summary> + /// The last line of paragraph is aligned to the flow's ending edge of the layout box. + /// </summary> + DWRITE_PARAGRAPH_ALIGNMENT_FAR, + + /// <summary> + /// The center of the paragraph is aligned to the center of the flow of the layout box. + /// </summary> + DWRITE_PARAGRAPH_ALIGNMENT_CENTER +}; + +/// <summary> +/// Word wrapping in multiline paragraph. +/// </summary> +enum DWRITE_WORD_WRAPPING +{ + /// <summary> + /// Words are broken across lines to avoid text overflowing the layout box. + /// </summary> + DWRITE_WORD_WRAPPING_WRAP, + + /// <summary> + /// 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. + /// </summary> + DWRITE_WORD_WRAPPING_NO_WRAP +}; + +/// <summary> +/// The method used for line spacing in layout. +/// </summary> +enum DWRITE_LINE_SPACING_METHOD +{ + /// <summary> + /// Line spacing depends solely on the content, growing to accomodate the size of fonts and inline objects. + /// </summary> + DWRITE_LINE_SPACING_METHOD_DEFAULT, + + /// <summary> + /// 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. + /// </summary> + DWRITE_LINE_SPACING_METHOD_UNIFORM +}; + +/// <summary> +/// Text granularity used to trim text overflowing the layout box. +/// </summary> +enum DWRITE_TRIMMING_GRANULARITY +{ + /// <summary> + /// No trimming occurs. Text flows beyond the layout width. + /// </summary> + DWRITE_TRIMMING_GRANULARITY_NONE, + + /// <summary> + /// Trimming occurs at character cluster boundary. + /// </summary> + DWRITE_TRIMMING_GRANULARITY_CHARACTER, + + /// <summary> + /// Trimming occurs at word boundary. + /// </summary> + DWRITE_TRIMMING_GRANULARITY_WORD +}; + +/// <summary> +/// Typographic feature of text supplied by the font. +/// </summary> +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' +}; + +/// <summary> +/// The DWRITE_TEXT_RANGE structure specifies a range of text positions where format is applied. +/// </summary> +struct DWRITE_TEXT_RANGE +{ + /// <summary> + /// The start text position of the range. + /// </summary> + UINT32 startPosition; + + /// <summary> + /// The number of text positions in the range. + /// </summary> + UINT32 length; +}; + +/// <summary> +/// The DWRITE_FONT_FEATURE structure specifies properties used to identify and execute typographic feature in the font. +/// </summary> +struct DWRITE_FONT_FEATURE +{ + /// <summary> + /// The feature OpenType name identifier. + /// </summary> + DWRITE_FONT_FEATURE_TAG nameTag; + + /// <summary> + /// Execution parameter of the feature. + /// </summary> + /// <remarks> + /// 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. + /// </remarks> + UINT32 parameter; +}; + +/// <summary> +/// 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. +/// </summary> +struct DWRITE_TYPOGRAPHIC_FEATURES +{ + /// <summary> + /// Array of font features. + /// </summary> + __field_ecount(featureCount) DWRITE_FONT_FEATURE* features; + + /// <summary> + /// The number of features. + /// </summary> + UINT32 featureCount; +}; + +/// <summary> +/// The DWRITE_TRIMMING structure specifies the trimming option for text overflowing the layout box. +/// </summary> +struct DWRITE_TRIMMING +{ + /// <summary> + /// Text granularity of which trimming applies. + /// </summary> + DWRITE_TRIMMING_GRANULARITY granularity; + + /// <summary> + /// 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. + /// </summary> + UINT32 delimiter; + + /// <summary> + /// How many occurences of the delimiter to step back. + /// </summary> + UINT32 delimiterCount; +}; + + +interface IDWriteTypography; +interface IDWriteInlineObject; + +/// <summary> +/// The format of text used for text layout purpose. +/// </summary> +/// <remarks> +/// This object may not be thread-safe and it may carry the state of text format change. +/// </remarks> +interface DWRITE_DECLARE_INTERFACE("9c906818-31d7-4fd3-a151-7c5e225db55a") IDWriteTextFormat : public IUnknown +{ + /// <summary> + /// Set alignment option of text relative to layout box's leading and trailing edge. + /// </summary> + /// <param name="textAlignment">Text alignment option</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(SetTextAlignment)( + DWRITE_TEXT_ALIGNMENT textAlignment + ) PURE; + + /// <summary> + /// Set alignment option of paragraph relative to layout box's top and bottom edge. + /// </summary> + /// <param name="paragraphAlignment">Paragraph alignment option</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(SetParagraphAlignment)( + DWRITE_PARAGRAPH_ALIGNMENT paragraphAlignment + ) PURE; + + /// <summary> + /// Set word wrapping option. + /// </summary> + /// <param name="wordWrapping">Word wrapping option</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(SetWordWrapping)( + DWRITE_WORD_WRAPPING wordWrapping + ) PURE; + + /// <summary> + /// Set paragraph reading direction. + /// </summary> + /// <param name="readingDirection">Text reading direction</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(SetReadingDirection)( + DWRITE_READING_DIRECTION readingDirection + ) PURE; + + /// <summary> + /// Set paragraph flow direction. + /// </summary> + /// <param name="flowDirection">Paragraph flow direction</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(SetFlowDirection)( + DWRITE_FLOW_DIRECTION flowDirection + ) PURE; + + /// <summary> + /// Set incremental tab stop position. + /// </summary> + /// <param name="incrementalTabStop">The incremental tab stop value</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(SetIncrementalTabStop)( + FLOAT incrementalTabStop + ) PURE; + + /// <summary> + /// Set trimming options for any trailing text exceeding the layout width + /// or for any far text exceeding the layout height. + /// </summary> + /// <param name="trimmingOptions">Text trimming options.</param> + /// <param name="trimmingSign">Application-defined omission sign. This parameter may be NULL if no trimming sign is desired.</param> + /// <remarks> + /// 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. + /// </remarks> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(SetTrimming)( + __in DWRITE_TRIMMING const* trimmingOptions, + IDWriteInlineObject* trimmingSign + ) PURE; + + /// <summary> + /// Set line spacing. + /// </summary> + /// <param name="lineSpacingMethod">How to determine line height.</param> + /// <param name="lineSpacing">The line height, or rather distance between one baseline to another.</param> + /// <param name="baseline">Distance from top of line to baseline. A reasonable ratio to lineSpacing is 80%.</param> + /// <remarks> + /// For the default method, spacing depends solely on the content. + /// For uniform spacing, the given line height will override the content. + /// </remarks> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(SetLineSpacing)( + DWRITE_LINE_SPACING_METHOD lineSpacingMethod, + FLOAT lineSpacing, + FLOAT baseline + ) PURE; + + /// <summary> + /// Get alignment option of text relative to layout box's leading and trailing edge. + /// </summary> + STDMETHOD_(DWRITE_TEXT_ALIGNMENT, GetTextAlignment)() PURE; + + /// <summary> + /// Get alignment option of paragraph relative to layout box's top and bottom edge. + /// </summary> + STDMETHOD_(DWRITE_PARAGRAPH_ALIGNMENT, GetParagraphAlignment)() PURE; + + /// <summary> + /// Get word wrapping option. + /// </summary> + STDMETHOD_(DWRITE_WORD_WRAPPING, GetWordWrapping)() PURE; + + /// <summary> + /// Get paragraph reading direction. + /// </summary> + STDMETHOD_(DWRITE_READING_DIRECTION, GetReadingDirection)() PURE; + + /// <summary> + /// Get paragraph flow direction. + /// </summary> + STDMETHOD_(DWRITE_FLOW_DIRECTION, GetFlowDirection)() PURE; + + /// <summary> + /// Get incremental tab stop position. + /// </summary> + STDMETHOD_(FLOAT, GetIncrementalTabStop)() PURE; + + /// <summary> + /// Get trimming options for text overflowing the layout width. + /// </summary> + /// <param name="trimmingOptions">Text trimming options.</param> + /// <param name="trimmingSign">Trimming omission sign. This parameter may be NULL.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetTrimming)( + __out DWRITE_TRIMMING* trimmingOptions, + __out IDWriteInlineObject** trimmingSign + ) PURE; + + /// <summary> + /// Get line spacing. + /// </summary> + /// <param name="lineSpacingMethod">How line height is determined.</param> + /// <param name="lineSpacing">The line height, or rather distance between one baseline to another.</param> + /// <param name="baseline">Distance from top of line to baseline.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetLineSpacing)( + __out DWRITE_LINE_SPACING_METHOD* lineSpacingMethod, + __out FLOAT* lineSpacing, + __out FLOAT* baseline + ) PURE; + + /// <summary> + /// Get the font collection. + /// </summary> + /// <param name="fontCollection">The current font collection.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetFontCollection)( + __out IDWriteFontCollection** fontCollection + ) PURE; + + /// <summary> + /// Get the length of the font family name, in characters, not including the terminating NULL character. + /// </summary> + STDMETHOD_(UINT32, GetFontFamilyNameLength)() PURE; + + /// <summary> + /// Get a copy of the font family name. + /// </summary> + /// <param name="fontFamilyName">Character array that receives the current font family name</param> + /// <param name="nameSize">Size of the character array in character count including the terminated NULL character.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetFontFamilyName)( + __out_ecount_z(nameSize) WCHAR* fontFamilyName, + UINT32 nameSize + ) PURE; + + /// <summary> + /// Get the font weight. + /// </summary> + STDMETHOD_(DWRITE_FONT_WEIGHT, GetFontWeight)() PURE; + + /// <summary> + /// Get the font style. + /// </summary> + STDMETHOD_(DWRITE_FONT_STYLE, GetFontStyle)() PURE; + + /// <summary> + /// Get the font stretch. + /// </summary> + STDMETHOD_(DWRITE_FONT_STRETCH, GetFontStretch)() PURE; + + /// <summary> + /// Get the font em height. + /// </summary> + STDMETHOD_(FLOAT, GetFontSize)() PURE; + + /// <summary> + /// Get the length of the locale name, in characters, not including the terminating NULL character. + /// </summary> + STDMETHOD_(UINT32, GetLocaleNameLength)() PURE; + + /// <summary> + /// Get a copy of the locale name. + /// </summary> + /// <param name="localeName">Character array that receives the current locale name</param> + /// <param name="nameSize">Size of the character array in character count including the terminated NULL character.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetLocaleName)( + __out_ecount_z(nameSize) WCHAR* localeName, + UINT32 nameSize + ) PURE; +}; + + +/// <summary> +/// Font typography setting. +/// </summary> +interface DWRITE_DECLARE_INTERFACE("55f1112b-1dc2-4b3c-9541-f46894ed85b6") IDWriteTypography : public IUnknown +{ + /// <summary> + /// Add font feature. + /// </summary> + /// <param name="fontFeature">The font feature to add.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(AddFontFeature)( + DWRITE_FONT_FEATURE fontFeature + ) PURE; + + /// <summary> + /// Get the number of font features. + /// </summary> + STDMETHOD_(UINT32, GetFontFeatureCount)() PURE; + + /// <summary> + /// Get the font feature at the specified index. + /// </summary> + /// <param name="fontFeatureIndex">The zero-based index of the font feature to get.</param> + /// <param name="fontFeature">The font feature.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetFontFeature)( + UINT32 fontFeatureIndex, + __out DWRITE_FONT_FEATURE* fontFeature + ) PURE; +}; + +enum DWRITE_SCRIPT_SHAPES +{ + /// <summary> + /// No additional shaping requirement. Text is shaped with the writing system default behavior. + /// </summary> + DWRITE_SCRIPT_SHAPES_DEFAULT = 0, + + /// <summary> + /// Text should leave no visual on display i.e. control or format control characters. + /// </summary> + DWRITE_SCRIPT_SHAPES_NO_VISUAL = 1 +}; + +#ifdef DEFINE_ENUM_FLAG_OPERATORS +DEFINE_ENUM_FLAG_OPERATORS(DWRITE_SCRIPT_SHAPES); +#endif + +/// <summary> +/// Association of text and its writing system script as well as some display attributes. +/// </summary> +struct DWRITE_SCRIPT_ANALYSIS +{ + /// <summary> + /// Zero-based index representation of writing system script. + /// </summary> + UINT16 script; + + /// <summary> + /// Additional shaping requirement of text. + /// </summary> + DWRITE_SCRIPT_SHAPES shapes; +}; + +/// <summary> +/// Condition at the edges of inline object or text used to determine +/// line-breaking behavior. +/// </summary> +enum DWRITE_BREAK_CONDITION +{ + /// <summary> + /// Whether a break is allowed is determined by the condition of the + /// neighboring text span or inline object. + /// </summary> + DWRITE_BREAK_CONDITION_NEUTRAL, + + /// <summary> + /// 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. + /// </summary> + DWRITE_BREAK_CONDITION_CAN_BREAK, + + /// <summary> + /// There should be no break, unless overruled by a Must condition from + /// the neighboring text span or inline object. + /// </summary> + DWRITE_BREAK_CONDITION_MAY_NOT_BREAK, + + /// <summary> + /// The break must happen, regardless of the condition of the adjacent + /// text span or inline object. + /// </summary> + DWRITE_BREAK_CONDITION_MUST_BREAK +}; + +/// <summary> +/// Line breakpoint characteristics of a character. +/// </summary> +struct DWRITE_LINE_BREAKPOINT +{ + /// <summary> + /// Breaking condition before the character. + /// </summary> + UINT8 breakConditionBefore : 2; + + /// <summary> + /// Breaking condition after the character. + /// </summary> + UINT8 breakConditionAfter : 2; + + /// <summary> + /// The character is some form of whitespace, which may be meaningful + /// for justification. + /// </summary> + UINT8 isWhitespace : 1; + + /// <summary> + /// The character is a soft hyphen, often used to indicate hyphenation + /// points inside words. + /// </summary> + UINT8 isSoftHyphen : 1; + + UINT8 padding : 2; +}; + +/// <summary> +/// How to apply number substitution on digits and related punctuation. +/// </summary> +enum DWRITE_NUMBER_SUBSTITUTION_METHOD +{ + /// <summary> + /// Specifies that the substitution method should be determined based + /// on LOCALE_IDIGITSUBSTITUTION value of the specified text culture. + /// </summary> + DWRITE_NUMBER_SUBSTITUTION_METHOD_FROM_CULTURE, + + /// <summary> + /// 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. + /// </summary> + DWRITE_NUMBER_SUBSTITUTION_METHOD_CONTEXTUAL, + + /// <summary> + /// Specifies that code points 0x30-0x39 are always rendered as nominal numeral + /// shapes (ones of the European number), i.e., no substitution is performed. + /// </summary> + DWRITE_NUMBER_SUBSTITUTION_METHOD_NONE, + + /// <summary> + /// Specifies that number are rendered using the national number shape + /// as specified by the LOCALE_SNATIVEDIGITS value of the specified text culture. + /// </summary> + DWRITE_NUMBER_SUBSTITUTION_METHOD_NATIONAL, + + /// <summary> + /// 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. + /// </summary> + DWRITE_NUMBER_SUBSTITUTION_METHOD_TRADITIONAL +}; + +/// <summary> +/// Holds the appropriate digits and numeric punctuation for a given locale. +/// </summary> +interface DECLSPEC_UUID("14885CC9-BAB0-4f90-B6ED-5C366A2CD03D") DECLSPEC_NOVTABLE IDWriteNumberSubstitution : public IUnknown +{ +}; + +/// <summary> +/// Shaping output properties per input character. +/// </summary> +struct DWRITE_SHAPING_TEXT_PROPERTIES +{ + /// <summary> + /// This character can be shaped independently from the others + /// (usually set for the space character). + /// </summary> + UINT16 isShapedAlone : 1; + + /// <summary> + /// Reserved for use by shaping engine. + /// </summary> + UINT16 reserved : 15; +}; + +/// <summary> +/// Shaping output properties per output glyph. +/// </summary> +struct DWRITE_SHAPING_GLYPH_PROPERTIES +{ + /// <summary> + /// Justification class, whether to use spacing, kashidas, or + /// another method. This exists for backwards compatibility + /// with Uniscribe's SCRIPT_JUSTIFY enum. + /// </summary> + UINT16 justification : 4; + + /// <summary> + /// Indicates glyph is the first of a cluster. + /// </summary> + UINT16 isClusterStart : 1; + + /// <summary> + /// Glyph is a diacritic. + /// </summary> + UINT16 isDiacritic : 1; + + /// <summary> + /// Glyph has no width, blank, ZWJ, ZWNJ etc. + /// </summary> + UINT16 isZeroWidthSpace : 1; + + /// <summary> + /// Reserved for use by shaping engine. + /// </summary> + UINT16 reserved : 9; +}; + +/// <summary> +/// 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. +/// </summary> +interface DECLSPEC_UUID("688e1a58-5094-47c8-adc8-fbcea60ae92b") DECLSPEC_NOVTABLE IDWriteTextAnalysisSource : public IUnknown +{ + /// <summary> + /// 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. + /// </summary> + /// <param name="textPosition">First position of the piece to obtain. All + /// positions are in UTF16 code-units, not whole characters, which + /// matters when supplementary characters are used.</param> + /// <param name="textString">Address that receives a pointer to the text block + /// at the specified position.</param> + /// <param name="textLength">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.</param> + /// <returns>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.</returns> + /// <remarks> + /// 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. + /// </remarks> + STDMETHOD(GetTextAtPosition)( + UINT32 textPosition, + __out WCHAR const** textString, + __out UINT32* textLength + ) PURE; + + /// <summary> + /// Get a block of text immediately preceding the specified position. + /// </summary> + /// <param name="textPosition">Position immediately after the last position of the chunk to obtain.</param> + /// <param name="textString">Address that receives a pointer to the text block + /// at the specified position.</param> + /// <param name="textLength">Number of UTF16 units of the retrieved block. + /// The length returned is from the given position to the front of + /// the block.</param> + /// <returns>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.</returns> + /// <remarks> + /// 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. + /// </remarks> + STDMETHOD(GetTextBeforePosition)( + UINT32 textPosition, + __out WCHAR const** textString, + __out UINT32* textLength + ) PURE; + + /// <summary> + /// Get paragraph reading direction. + /// </summary> + STDMETHOD_(DWRITE_READING_DIRECTION, GetParagraphReadingDirection)() PURE; + + /// <summary> + /// Get locale name on the range affected by it. + /// </summary> + /// <param name="textPosition">Position to get the locale name of.</param> + /// <param name="textLength">Receives the length from the given position up to the + /// next differing locale.</param> + /// <param name="localeName">Address that receives a pointer to the locale + /// at the specified position.</param> + /// <remarks> + /// The localeName pointer must remain valid until the next call or until + /// the analysis returns. + /// </remarks> + STDMETHOD(GetLocaleName)( + UINT32 textPosition, + __out UINT32* textLength, + __out_z WCHAR const** localeName + ) PURE; + + /// <summary> + /// Get number substitution on the range affected by it. + /// </summary> + /// <param name="textPosition">Position to get the number substitution of.</param> + /// <param name="textLength">Receives the length from the given position up to the + /// next differing number substitution.</param> + /// <param name="numberSubstitution">Address that receives a pointer to the number substitution + /// at the specified position.</param> + /// <remarks> + /// 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. + /// </remarks> + STDMETHOD(GetNumberSubstitution)( + UINT32 textPosition, + __out UINT32* textLength, + __out IDWriteNumberSubstitution** numberSubstitution + ) PURE; +}; + +/// <summary> +/// 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. +/// </summary> +interface DECLSPEC_UUID("5810cd44-0ca0-4701-b3fa-bec5182ae4f6") DECLSPEC_NOVTABLE IDWriteTextAnalysisSink : public IUnknown +{ + /// <summary> + /// Report script analysis for the text range. + /// </summary> + /// <param name="textPosition">Starting position to report from.</param> + /// <param name="textLength">Number of UTF16 units of the reported range.</param> + /// <param name="scriptAnalysis">Script analysis of characters in range.</param> + /// <returns> + /// A successful code or error code to abort analysis. + /// </returns> + STDMETHOD(SetScriptAnalysis)( + UINT32 textPosition, + UINT32 textLength, + __in DWRITE_SCRIPT_ANALYSIS const* scriptAnalysis + ) PURE; + + /// <summary> + /// Repport line-break opportunities for each character, starting from + /// the specified position. + /// </summary> + /// <param name="textPosition">Starting position to report from.</param> + /// <param name="textLength">Number of UTF16 units of the reported range.</param> + /// <param name="lineBreakpoints">Breaking conditions for each character.</param> + /// <returns> + /// A successful code or error code to abort analysis. + /// </returns> + STDMETHOD(SetLineBreakpoints)( + UINT32 textPosition, + UINT32 textLength, + __in_ecount(textLength) DWRITE_LINE_BREAKPOINT const* lineBreakpoints + ) PURE; + + /// <summary> + /// Set bidirectional level on the range, called once per each + /// level run change (either explicit or resolved implicit). + /// </summary> + /// <param name="textPosition">Starting position to report from.</param> + /// <param name="textLength">Number of UTF16 units of the reported range.</param> + /// <param name="explicitLevel">Explicit level from embedded control codes + /// RLE/RLO/LRE/LRO/PDF, determined before any additional rules.</param> + /// <param name="resolvedLevel">Final implicit level considering the + /// explicit level and characters' natural directionality, after all + /// Bidi rules have been applied.</param> + /// <returns> + /// A successful code or error code to abort analysis. + /// </returns> + STDMETHOD(SetBidiLevel)( + UINT32 textPosition, + UINT32 textLength, + UINT8 explicitLevel, + UINT8 resolvedLevel + ) PURE; + + /// <summary> + /// Set number substitution on the range. + /// </summary> + /// <param name="textPosition">Starting position to report from.</param> + /// <param name="textLength">Number of UTF16 units of the reported range.</param> + /// <param name="numberSubstitution">The number substitution applicable to + /// the returned range of text. The sink callback may hold onto it by + /// incrementing its ref count.</param> + /// <returns> + /// A successful code or error code to abort analysis. + /// </returns> + /// <remark> + /// 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. + /// </remark> + STDMETHOD(SetNumberSubstitution)( + UINT32 textPosition, + UINT32 textLength, + __notnull IDWriteNumberSubstitution* numberSubstitution + ) PURE; +}; + +/// <summary> +/// Analyzes various text properties for complex script processing. +/// </summary> +interface DWRITE_DECLARE_INTERFACE("b7e6163e-7f46-43b4-84b3-e4e6249c365d") IDWriteTextAnalyzer : public IUnknown +{ + /// <summary> + /// Analyzes a text range for script boundaries, reading text attributes + /// from the source and reporting the Unicode script ID to the sink + /// callback SetScript. + /// </summary> + /// <param name="analysisSource">Source object to analyze.</param> + /// <param name="textPosition">Starting position within the source object.</param> + /// <param name="textLength">Length to analyze.</param> + /// <param name="analysisSink">Callback object.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(AnalyzeScript)( + IDWriteTextAnalysisSource* analysisSource, + UINT32 textPosition, + UINT32 textLength, + IDWriteTextAnalysisSink* analysisSink + ) PURE; + + /// <summary> + /// Analyzes a text range for script directionality, reading attributes + /// from the source and reporting levels to the sink callback SetBidiLevel. + /// </summary> + /// <param name="analysisSource">Source object to analyze.</param> + /// <param name="textPosition">Starting position within the source object.</param> + /// <param name="textLength">Length to analyze.</param> + /// <param name="analysisSink">Callback object.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + /// <remarks> + /// 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. + /// </remarks> + /// <remarks> + /// Embedded control codes (LRE/LRO/RLE/RLO/PDF) are taken into account. + /// </remarks> + STDMETHOD(AnalyzeBidi)( + IDWriteTextAnalysisSource* analysisSource, + UINT32 textPosition, + UINT32 textLength, + IDWriteTextAnalysisSink* analysisSink + ) PURE; + + /// <summary> + /// 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. + /// </summary> + /// <param name="analysisSource">Source object to analyze.</param> + /// <param name="textPosition">Starting position within the source object.</param> + /// <param name="textLength">Length to analyze.</param> + /// <param name="analysisSink">Callback object.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + /// <remarks> + /// 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. + /// </remarks> + /// <remarks> + /// Embedded control codes (LRE/LRO/RLE/RLO/PDF) are taken into account. + /// </remarks> + STDMETHOD(AnalyzeNumberSubstitution)( + IDWriteTextAnalysisSource* analysisSource, + UINT32 textPosition, + UINT32 textLength, + IDWriteTextAnalysisSink* analysisSink + ) PURE; + + /// <summary> + /// Analyzes a text range for potential breakpoint opportunities, reading + /// attributes from the source and reporting breakpoint opportunities to + /// the sink callback SetLineBreakpoints. + /// </summary> + /// <param name="analysisSource">Source object to analyze.</param> + /// <param name="textPosition">Starting position within the source object.</param> + /// <param name="textLength">Length to analyze.</param> + /// <param name="analysisSink">Callback object.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + /// <remarks> + /// 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. + /// </remarks> + /// <remarks> + /// 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. + /// </remarks> + STDMETHOD(AnalyzeLineBreakpoints)( + IDWriteTextAnalysisSource* analysisSource, + UINT32 textPosition, + UINT32 textLength, + IDWriteTextAnalysisSink* analysisSink + ) PURE; + + /// <summary> + /// 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. + /// </summary> + /// <param name="textString">The string to convert to glyphs.</param> + /// <param name="textLength">The length of textString.</param> + /// <param name="fontFace">The font face to get glyphs from.</param> + /// <param name="isSideways">Set to true if the text is intended to be + /// drawn vertically.</param> + /// <param name="isRightToLeft">Set to TRUE for right-to-left text.</param> + /// <param name="scriptAnalysis">Script analysis result from AnalyzeScript.</param> + /// <param name="localeName">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.</param> + /// <param name="numberSubstitution">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.</param> + /// <param name="features">An array of pointers to the sets of typographic + /// features to use in each feature range.</param> + /// <param name="featureRangeLengths">The length of each feature range, in characters. + /// The sum of all lengths should be equal to textLength.</param> + /// <param name="featureRanges">The number of feature ranges.</param> + /// <param name="maxGlyphCount">The maximum number of glyphs that can be + /// returned.</param> + /// <param name="clusterMap">The mapping from character ranges to glyph + /// ranges.</param> + /// <param name="textProps">Per-character output properties.</param> + /// <param name="glyphIndices">Output glyph indices.</param> + /// <param name="glyphProps">Per-glyph output properties.</param> + /// <param name="actualGlyphCount">The actual number of glyphs returned if + /// the call succeeds.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + /// <remarks> + /// 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. + /// </remarks> + 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; + + /// <summary> + /// Place glyphs output from the GetGlyphs method according to the font + /// and the writing system's rendering rules. + /// </summary> + /// <param name="textString">The original string the glyphs came from.</param> + /// <param name="clusterMap">The mapping from character ranges to glyph + /// ranges. Returned by GetGlyphs.</param> + /// <param name="textProps">Per-character properties. Returned by + /// GetGlyphs.</param> + /// <param name="textLength">The length of textString.</param> + /// <param name="glyphIndices">Glyph indices. See GetGlyphs</param> + /// <param name="glyphProps">Per-glyph properties. See GetGlyphs</param> + /// <param name="glyphCount">The number of glyphs.</param> + /// <param name="fontFace">The font face the glyphs came from.</param> + /// <param name="fontEmSize">Logical font size in DIP's.</param> + /// <param name="isSideways">Set to true if the text is intended to be + /// drawn vertically.</param> + /// <param name="isRightToLeft">Set to TRUE for right-to-left text.</param> + /// <param name="scriptAnalysis">Script analysis result from AnalyzeScript.</param> + /// <param name="localeName">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.</param> + /// <param name="features">An array of pointers to the sets of typographic + /// features to use in each feature range.</param> + /// <param name="featureRangeLengths">The length of each feature range, in characters. + /// The sum of all lengths should be equal to textLength.</param> + /// <param name="featureRanges">The number of feature ranges.</param> + /// <param name="glyphAdvances">The advance width of each glyph.</param> + /// <param name="glyphOffsets">The offset of the origin of each glyph.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + 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; + + /// <summary> + /// Place glyphs output from the GetGlyphs method according to the font + /// and the writing system's rendering rules. + /// </summary> + /// <param name="textString">The original string the glyphs came from.</param> + /// <param name="clusterMap">The mapping from character ranges to glyph + /// ranges. Returned by GetGlyphs.</param> + /// <param name="textProps">Per-character properties. Returned by + /// GetGlyphs.</param> + /// <param name="textLength">The length of textString.</param> + /// <param name="glyphIndices">Glyph indices. See GetGlyphs</param> + /// <param name="glyphProps">Per-glyph properties. See GetGlyphs</param> + /// <param name="glyphCount">The number of glyphs.</param> + /// <param name="fontFace">The font face the glyphs came from.</param> + /// <param name="fontEmSize">Logical font size in DIP's.</param> + /// <param name="pixelsPerDip">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.</param> + /// <param name="transform">Optional transform applied to the glyphs and their positions. This transform is applied after the + /// scaling specified by the font size and pixelsPerDip.</param> + /// <param name="useGdiNatural"> + /// 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. + /// </param> + /// <param name="isSideways">Set to true if the text is intended to be + /// drawn vertically.</param> + /// <param name="isRightToLeft">Set to TRUE for right-to-left text.</param> + /// <param name="scriptAnalysis">Script analysis result from AnalyzeScript.</param> + /// <param name="localeName">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.</param> + /// <param name="features">An array of pointers to the sets of typographic + /// features to use in each feature range.</param> + /// <param name="featureRangeLengths">The length of each feature range, in characters. + /// The sum of all lengths should be equal to textLength.</param> + /// <param name="featureRanges">The number of feature ranges.</param> + /// <param name="glyphAdvances">The advance width of each glyph.</param> + /// <param name="glyphOffsets">The offset of the origin of each glyph.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + 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; +}; + +/// <summary> +/// The DWRITE_GLYPH_RUN structure contains the information needed by renderers +/// to draw glyph runs. All coordinates are in device independent pixels (DIPs). +/// </summary> +struct DWRITE_GLYPH_RUN +{ + /// <summary> + /// The physical font face to draw with. + /// </summary> + __notnull IDWriteFontFace* fontFace; + + /// <summary> + /// Logical size of the font in DIPs, not points (equals 1/96 inch). + /// </summary> + FLOAT fontEmSize; + + /// <summary> + /// The number of glyphs. + /// </summary> + UINT32 glyphCount; + + /// <summary> + /// The indices to render. + /// </summary> + __field_ecount(glyphCount) UINT16 const* glyphIndices; + + /// <summary> + /// Glyph advance widths. + /// </summary> + __field_ecount_opt(glyphCount) FLOAT const* glyphAdvances; + + /// <summary> + /// Glyph offsets. + /// </summary> + __field_ecount_opt(glyphCount) DWRITE_GLYPH_OFFSET const* glyphOffsets; + + /// <summary> + /// 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. + /// </summary> + BOOL isSideways; + + /// <summary> + /// 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. + /// </summary> + UINT32 bidiLevel; +}; + +/// <summary> +/// The DWRITE_GLYPH_RUN_DESCRIPTION structure contains additional properties +/// related to those in DWRITE_GLYPH_RUN. +/// </summary> +struct DWRITE_GLYPH_RUN_DESCRIPTION +{ + /// <summary> + /// The locale name associated with this run. + /// </summary> + __nullterminated WCHAR const* localeName; + + /// <summary> + /// The text associated with the glyphs. + /// </summary> + __field_ecount(stringLength) WCHAR const* string; + + /// <summary> + /// The number of characters (UTF16 code-units). + /// Note that this may be different than the number of glyphs. + /// </summary> + UINT32 stringLength; + + /// <summary> + /// An array of indices to the glyph indices array, of the first glyphs of + /// all the glyph clusters of the glyphs to render. + /// </summary> + __field_ecount(stringLength) UINT16 const* clusterMap; + + /// <summary> + /// Corresponding text position in the original string + /// this glyph run came from. + /// </summary> + UINT32 textPosition; +}; + +/// <summary> +/// The DWRITE_UNDERLINE structure contains about the size and placement of +/// underlines. All coordinates are in device independent pixels (DIPs). +/// </summary> +struct DWRITE_UNDERLINE +{ + /// <summary> + /// Width of the underline, measured parallel to the baseline. + /// </summary> + FLOAT width; + + /// <summary> + /// Thickness of the underline, measured perpendicular to the + /// baseline. + /// </summary> + FLOAT thickness; + + /// <summary> + /// Offset of the underline from the baseline. + /// A positive offset represents a position below the baseline and + /// a negative offset is above. + /// </summary> + FLOAT offset; + + /// <summary> + /// Height of the tallest run where the underline applies. + /// </summary> + FLOAT runHeight; + + /// <summary> + /// Reading direction of the text associated with the underline. This + /// value is used to interpret whether the width value runs horizontally + /// or vertically. + /// </summary> + DWRITE_READING_DIRECTION readingDirection; + + /// <summary> + /// 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. + /// </summary> + DWRITE_FLOW_DIRECTION flowDirection; + + /// <summary> + /// 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. + /// </summary> + __nullterminated WCHAR const* localeName; + + /// <summary> + /// 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. + /// </summary> + DWRITE_MEASURING_MODE measuringMode; +}; + +/// <summary> +/// The DWRITE_STRIKETHROUGH structure contains about the size and placement of +/// strickthroughs. All coordinates are in device independent pixels (DIPs). +/// </summary> +struct DWRITE_STRIKETHROUGH +{ + /// <summary> + /// Width of the strikethrough, measured parallel to the baseline. + /// </summary> + FLOAT width; + + /// <summary> + /// Thickness of the strikethrough, measured perpendicular to the + /// baseline. + /// </summary> + FLOAT thickness; + + /// <summary> + /// Offset of the stikethrough from the baseline. + /// A positive offset represents a position below the baseline and + /// a negative offset is above. + /// </summary> + FLOAT offset; + + /// <summary> + /// Reading direction of the text associated with the strikethrough. This + /// value is used to interpret whether the width value runs horizontally + /// or vertically. + /// </summary> + DWRITE_READING_DIRECTION readingDirection; + + /// <summary> + /// 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. + /// </summary> + DWRITE_FLOW_DIRECTION flowDirection; + + /// <summary> + /// Locale of the range. Can be pertinent where the locale affects the style. + /// </summary> + __nullterminated WCHAR const* localeName; + + /// <summary> + /// 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. + /// </summary> + DWRITE_MEASURING_MODE measuringMode; +}; + +/// <summary> +/// The DWRITE_LINE_METRICS structure contains information about a formatted +/// line of text. +/// </summary> +struct DWRITE_LINE_METRICS +{ + /// <summary> + /// The number of total text positions in the line. + /// This includes any trailing whitespace and newline characters. + /// </summary> + UINT32 length; + + /// <summary> + /// The number of whitespace positions at the end of the line. Newline + /// sequences are considered whitespace. + /// </summary> + UINT32 trailingWhitespaceLength; + + /// <summary> + /// 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. + /// </summary> + UINT32 newlineLength; + + /// <summary> + /// Height of the line as measured from top to bottom. + /// </summary> + FLOAT height; + + /// <summary> + /// Distance from the top of the line to its baseline. + /// </summary> + FLOAT baseline; + + /// <summary> + /// The line is trimmed. + /// </summary> + BOOL isTrimmed; +}; + + +/// <summary> +/// The DWRITE_CLUSTER_METRICS structure contains information about a glyph cluster. +/// </summary> +struct DWRITE_CLUSTER_METRICS +{ + /// <summary> + /// The total advance width of all glyphs in the cluster. + /// </summary> + FLOAT width; + + /// <summary> + /// The number of text positions in the cluster. + /// </summary> + UINT16 length; + + /// <summary> + /// Indicate whether line can be broken right after the cluster. + /// </summary> + UINT16 canWrapLineAfter : 1; + + /// <summary> + /// Indicate whether the cluster corresponds to whitespace character. + /// </summary> + UINT16 isWhitespace : 1; + + /// <summary> + /// Indicate whether the cluster corresponds to a newline character. + /// </summary> + UINT16 isNewline : 1; + + /// <summary> + /// Indicate whether the cluster corresponds to soft hyphen character. + /// </summary> + UINT16 isSoftHyphen : 1; + + /// <summary> + /// Indicate whether the cluster is read from right to left. + /// </summary> + UINT16 isRightToLeft : 1; + + UINT16 padding : 11; +}; + + +/// <summary> +/// Overall metrics associated with text after layout. +/// All coordinates are in device independent pixels (DIPs). +/// </summary> +struct DWRITE_TEXT_METRICS +{ + /// <summary> + /// Left-most point of formatted text relative to layout box + /// (excluding any glyph overhang). + /// </summary> + FLOAT left; + + /// <summary> + /// Top-most point of formatted text relative to layout box + /// (excluding any glyph overhang). + /// </summary> + FLOAT top; + + /// <summary> + /// The width of the formatted text ignoring trailing whitespace + /// at the end of each line. + /// </summary> + FLOAT width; + + /// <summary> + /// The width of the formatted text taking into account the + /// trailing whitespace at the end of each line. + /// </summary> + FLOAT widthIncludingTrailingWhitespace; + + /// <summary> + /// The height of the formatted text. The height of an empty string + /// is determined by the size of the default font's line height. + /// </summary> + FLOAT height; + + /// <summary> + /// 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. + /// </summary> + FLOAT layoutWidth; + + /// <summary> + /// Initial height given to the layout. Depending on the length of the + /// text, it may be larger or smaller than the text content height. + /// </summary> + FLOAT layoutHeight; + + /// <summary> + /// 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. + /// </summary> + UINT32 maxBidiReorderingDepth; + + /// <summary> + /// Total number of lines. + /// </summary> + UINT32 lineCount; +}; + + +/// <summary> +/// Properties describing the geometric measurement of an +/// application-defined inline object. +/// </summary> +struct DWRITE_INLINE_OBJECT_METRICS +{ + /// <summary> + /// Width of the inline object. + /// </summary> + FLOAT width; + + /// <summary> + /// Height of the inline object as measured from top to bottom. + /// </summary> + FLOAT height; + + /// <summary> + /// 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. + /// </summary> + FLOAT baseline; + + /// <summary> + /// Flag indicating whether the object is to be placed upright or alongside the text baseline + /// for vertical text. + /// </summary> + BOOL supportsSideways; +}; + + +/// <summary> +/// The DWRITE_OVERHANG_METRICS structure holds how much any visible pixels +/// (in DIPs) overshoot each side of the layout or inline objects. +/// </summary> +/// <remarks> +/// 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. +/// </remarks> +struct DWRITE_OVERHANG_METRICS +{ + /// <summary> + /// The distance from the left-most visible DIP to its left alignment edge. + /// </summary> + FLOAT left; + + /// <summary> + /// The distance from the top-most visible DIP to its top alignment edge. + /// </summary> + FLOAT top; + + /// <summary> + /// The distance from the right-most visible DIP to its right alignment edge. + /// </summary> + FLOAT right; + + /// <summary> + /// The distance from the bottom-most visible DIP to its bottom alignment edge. + /// </summary> + FLOAT bottom; +}; + + +/// <summary> +/// Geometry enclosing of text positions. +/// </summary> +struct DWRITE_HIT_TEST_METRICS +{ + /// <summary> + /// First text position within the geometry. + /// </summary> + UINT32 textPosition; + + /// <summary> + /// Number of text positions within the geometry. + /// </summary> + UINT32 length; + + /// <summary> + /// Left position of the top-left coordinate of the geometry. + /// </summary> + FLOAT left; + + /// <summary> + /// Top position of the top-left coordinate of the geometry. + /// </summary> + FLOAT top; + + /// <summary> + /// Geometry's width. + /// </summary> + FLOAT width; + + /// <summary> + /// Geometry's height. + /// </summary> + FLOAT height; + + /// <summary> + /// Bidi level of text positions enclosed within the geometry. + /// </summary> + UINT32 bidiLevel; + + /// <summary> + /// Geometry encloses text? + /// </summary> + BOOL isText; + + /// <summary> + /// Range is trimmed. + /// </summary> + BOOL isTrimmed; +}; + + +interface IDWriteTextRenderer; + + +/// <summary> +/// The IDWriteInlineObject interface wraps an application defined inline graphic, +/// allowing DWrite to query metrics as if it was a glyph inline with the text. +/// </summary> +interface DWRITE_DECLARE_INTERFACE("8339FDE3-106F-47ab-8373-1C6295EB10B3") IDWriteInlineObject : public IUnknown +{ + /// <summary> + /// 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. + /// </summary> + /// <param name="clientDrawingContext">The context passed to IDWriteTextLayout::Draw.</param> + /// <param name="renderer">The renderer passed to IDWriteTextLayout::Draw as the object's containing parent.</param> + /// <param name="originX">X-coordinate at the top-left corner of the inline object.</param> + /// <param name="originY">Y-coordinate at the top-left corner of the inline object.</param> + /// <param name="isSideways">The object should be drawn on its side.</param> + /// <param name="isRightToLeft">The object is in an right-to-left context and should be drawn flipped.</param> + /// <param name="clientDrawingEffect">The drawing effect set in IDWriteTextLayout::SetDrawingEffect.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(Draw)( + __maybenull void* clientDrawingContext, + IDWriteTextRenderer* renderer, + FLOAT originX, + FLOAT originY, + BOOL isSideways, + BOOL isRightToLeft, + __maybenull IUnknown* clientDrawingEffect + ) PURE; + + /// <summary> + /// TextLayout calls this callback function to get the measurement of the inline object. + /// </summary> + /// <param name="metrics">Returned metrics</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetMetrics)( + __out DWRITE_INLINE_OBJECT_METRICS* metrics + ) PURE; + + /// <summary> + /// 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. + /// </summary> + /// <param name="overhangs">Overshoot of visible extents (in DIPs) outside the object.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + /// <remarks> + /// 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. + /// </remarks> + STDMETHOD(GetOverhangMetrics)( + __out DWRITE_OVERHANG_METRICS* overhangs + ) PURE; + + /// <summary> + /// Layout uses this to determine the line breaking behavior of the inline object + /// amidst the text. + /// </summary> + /// <param name="breakConditionBefore">Line-breaking condition between the object and the content immediately preceding it.</param> + /// <param name="breakConditionAfter" >Line-breaking condition between the object and the content immediately following it.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetBreakConditions)( + __out DWRITE_BREAK_CONDITION* breakConditionBefore, + __out DWRITE_BREAK_CONDITION* breakConditionAfter + ) PURE; +}; + +/// <summary> +/// The IDWritePixelSnapping interface defines the pixel snapping properties of a text renderer. +/// </summary> +interface DWRITE_DECLARE_INTERFACE("eaf3a2da-ecf4-4d24-b644-b34f6842024b") IDWritePixelSnapping : public IUnknown +{ + /// <summary> + /// Determines whether pixel snapping is disabled. The recommended default is FALSE, + /// unless doing animation that requires subpixel vertical placement. + /// </summary> + /// <param name="clientDrawingContext">The context passed to IDWriteTextLayout::Draw.</param> + /// <param name="isDisabled">Receives TRUE if pixel snapping is disabled or FALSE if it not.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(IsPixelSnappingDisabled)( + __maybenull void* clientDrawingContext, + __out BOOL* isDisabled + ) PURE; + + /// <summary> + /// Gets the current transform that maps abstract coordinates to DIPs, + /// which may disable pixel snapping upon any rotation or shear. + /// </summary> + /// <param name="clientDrawingContext">The context passed to IDWriteTextLayout::Draw.</param> + /// <param name="transform">Receives the transform.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetCurrentTransform)( + __maybenull void* clientDrawingContext, + __out DWRITE_MATRIX* transform + ) PURE; + + /// <summary> + /// 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). + /// </summary> + /// <param name="clientDrawingContext">The context passed to IDWriteTextLayout::Draw.</param> + /// <param name="pixelsPerDip">Receives the number of physical pixels per DIP.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetPixelsPerDip)( + __maybenull void* clientDrawingContext, + __out FLOAT* pixelsPerDip + ) PURE; +}; + +/// <summary> +/// The IDWriteTextLayout interface represents a set of application-defined +/// callbacks that perform rendering of text, inline objects, and decorations +/// such as underlines. +/// </summary> +interface DWRITE_DECLARE_INTERFACE("ef8a8135-5cc6-45fe-8825-c5a0724eb819") IDWriteTextRenderer : public IDWritePixelSnapping +{ + /// <summary> + /// IDWriteTextLayout::Draw calls this function to instruct the client to + /// render a run of glyphs. + /// </summary> + /// <param name="clientDrawingContext">The context passed to + /// IDWriteTextLayout::Draw.</param> + /// <param name="baselineOriginX">X-coordinate of the baseline.</param> + /// <param name="baselineOriginY">Y-coordinate of the baseline.</param> + /// <param name="measuringMode">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 + /// </param> + /// <param name="glyphRun">The glyph run to draw.</param> + /// <param name="glyphRunDescription">Properties of the characters + /// associated with this run.</param> + /// <param name="clientDrawingEffect">The drawing effect set in + /// IDWriteTextLayout::SetDrawingEffect.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + 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; + + /// <summary> + /// IDWriteTextLayout::Draw calls this function to instruct the client to draw + /// an underline. + /// </summary> + /// <param name="clientDrawingContext">The context passed to + /// IDWriteTextLayout::Draw.</param> + /// <param name="baselineOriginX">X-coordinate of the baseline.</param> + /// <param name="baselineOriginY">Y-coordinate of the baseline.</param> + /// <param name="underline">Underline logical information.</param> + /// <param name="clientDrawingEffect">The drawing effect set in + /// IDWriteTextLayout::SetDrawingEffect.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + /// <remarks> + /// 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. + /// </remarks> + STDMETHOD(DrawUnderline)( + __maybenull void* clientDrawingContext, + FLOAT baselineOriginX, + FLOAT baselineOriginY, + __in DWRITE_UNDERLINE const* underline, + __maybenull IUnknown* clientDrawingEffect + ) PURE; + + /// <summary> + /// IDWriteTextLayout::Draw calls this function to instruct the client to draw + /// a strikethrough. + /// </summary> + /// <param name="clientDrawingContext">The context passed to + /// IDWriteTextLayout::Draw.</param> + /// <param name="baselineOriginX">X-coordinate of the baseline.</param> + /// <param name="baselineOriginY">Y-coordinate of the baseline.</param> + /// <param name="strikethrough">Strikethrough logical information.</param> + /// <param name="clientDrawingEffect">The drawing effect set in + /// IDWriteTextLayout::SetDrawingEffect.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + /// <remarks> + /// 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. + /// </remarks> + STDMETHOD(DrawStrikethrough)( + __maybenull void* clientDrawingContext, + FLOAT baselineOriginX, + FLOAT baselineOriginY, + __in DWRITE_STRIKETHROUGH const* strikethrough, + __maybenull IUnknown* clientDrawingEffect + ) PURE; + + /// <summary> + /// IDWriteTextLayout::Draw calls this application callback when it needs to + /// draw an inline object. + /// </summary> + /// <param name="clientDrawingContext">The context passed to IDWriteTextLayout::Draw.</param> + /// <param name="originX">X-coordinate at the top-left corner of the inline object.</param> + /// <param name="originY">Y-coordinate at the top-left corner of the inline object.</param> + /// <param name="inlineObject">The object set using IDWriteTextLayout::SetInlineObject.</param> + /// <param name="isSideways">The object should be drawn on its side.</param> + /// <param name="isRightToLeft">The object is in an right-to-left context and should be drawn flipped.</param> + /// <param name="clientDrawingEffect">The drawing effect set in + /// IDWriteTextLayout::SetDrawingEffect.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + /// <remarks> + /// 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). + /// </remarks> + STDMETHOD(DrawInlineObject)( + __maybenull void* clientDrawingContext, + FLOAT originX, + FLOAT originY, + IDWriteInlineObject* inlineObject, + BOOL isSideways, + BOOL isRightToLeft, + __maybenull IUnknown* clientDrawingEffect + ) PURE; +}; + +/// <summary> +/// The IDWriteTextLayout interface represents a block of text after it has +/// been fully analyzed and formatted. +/// +/// All coordinates are in device independent pixels (DIPs). +/// </summary> +interface DWRITE_DECLARE_INTERFACE("53737037-6d14-410b-9bfe-0b182bb70961") IDWriteTextLayout : public IDWriteTextFormat +{ + /// <summary> + /// Set layout maximum width + /// </summary> + /// <param name="maxWidth">Layout maximum width</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(SetMaxWidth)( + FLOAT maxWidth + ) PURE; + + /// <summary> + /// Set layout maximum height + /// </summary> + /// <param name="maxHeight">Layout maximum height</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(SetMaxHeight)( + FLOAT maxHeight + ) PURE; + + /// <summary> + /// Set the font collection. + /// </summary> + /// <param name="fontCollection">The font collection to set</param> + /// <param name="textRange">Text range to which this change applies.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(SetFontCollection)( + IDWriteFontCollection* fontCollection, + DWRITE_TEXT_RANGE textRange + ) PURE; + + /// <summary> + /// Set null-terminated font family name. + /// </summary> + /// <param name="fontFamilyName">Font family name</param> + /// <param name="textRange">Text range to which this change applies.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(SetFontFamilyName)( + __in_z WCHAR const* fontFamilyName, + DWRITE_TEXT_RANGE textRange + ) PURE; + + /// <summary> + /// Set font weight. + /// </summary> + /// <param name="fontWeight">Font weight</param> + /// <param name="textRange">Text range to which this change applies.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(SetFontWeight)( + DWRITE_FONT_WEIGHT fontWeight, + DWRITE_TEXT_RANGE textRange + ) PURE; + + /// <summary> + /// Set font style. + /// </summary> + /// <param name="fontStyle">Font style</param> + /// <param name="textRange">Text range to which this change applies.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(SetFontStyle)( + DWRITE_FONT_STYLE fontStyle, + DWRITE_TEXT_RANGE textRange + ) PURE; + + /// <summary> + /// Set font stretch. + /// </summary> + /// <param name="fontStretch">font stretch</param> + /// <param name="textRange">Text range to which this change applies.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(SetFontStretch)( + DWRITE_FONT_STRETCH fontStretch, + DWRITE_TEXT_RANGE textRange + ) PURE; + + /// <summary> + /// Set font em height. + /// </summary> + /// <param name="fontSize">Font em height</param> + /// <param name="textRange">Text range to which this change applies.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(SetFontSize)( + FLOAT fontSize, + DWRITE_TEXT_RANGE textRange + ) PURE; + + /// <summary> + /// Set underline. + /// </summary> + /// <param name="hasUnderline">The Boolean flag indicates whether underline takes place</param> + /// <param name="textRange">Text range to which this change applies.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(SetUnderline)( + BOOL hasUnderline, + DWRITE_TEXT_RANGE textRange + ) PURE; + + /// <summary> + /// Set strikethrough. + /// </summary> + /// <param name="hasStrikethrough">The Boolean flag indicates whether strikethrough takes place</param> + /// <param name="textRange">Text range to which this change applies.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(SetStrikethrough)( + BOOL hasStrikethrough, + DWRITE_TEXT_RANGE textRange + ) PURE; + + /// <summary> + /// Set application-defined drawing effect. + /// </summary> + /// <param name="drawingEffect">Pointer to an application-defined drawing effect.</param> + /// <param name="textRange">Text range to which this change applies.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + /// <remarks> + /// 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. + /// </remarks> + STDMETHOD(SetDrawingEffect)( + IUnknown* drawingEffect, + DWRITE_TEXT_RANGE textRange + ) PURE; + + /// <summary> + /// Set inline object. + /// </summary> + /// <param name="inlineObject">Pointer to an application-implemented inline object.</param> + /// <param name="textRange">Text range to which this change applies.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + /// <remarks> + /// 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. + /// </remarks> + STDMETHOD(SetInlineObject)( + IDWriteInlineObject* inlineObject, + DWRITE_TEXT_RANGE textRange + ) PURE; + + /// <summary> + /// Set font typography features. + /// </summary> + /// <param name="typography">Pointer to font typography setting.</param> + /// <param name="textRange">Text range to which this change applies.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(SetTypography)( + IDWriteTypography* typography, + DWRITE_TEXT_RANGE textRange + ) PURE; + + /// <summary> + /// Set locale name. + /// </summary> + /// <param name="localeName">Locale name</param> + /// <param name="textRange">Text range to which this change applies.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(SetLocaleName)( + __in_z WCHAR const* localeName, + DWRITE_TEXT_RANGE textRange + ) PURE; + + /// <summary> + /// Get layout maximum width + /// </summary> + STDMETHOD_(FLOAT, GetMaxWidth)() PURE; + + /// <summary> + /// Get layout maximum height + /// </summary> + STDMETHOD_(FLOAT, GetMaxHeight)() PURE; + + /// <summary> + /// Get the font collection where the current position is at. + /// </summary> + /// <param name="currentPosition">The current text position.</param> + /// <param name="fontCollection">The current font collection</param> + /// <param name="textRange">Text range to which this change applies.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetFontCollection)( + UINT32 currentPosition, + __out IDWriteFontCollection** fontCollection, + __out_opt DWRITE_TEXT_RANGE* textRange = NULL + ) PURE; + + /// <summary> + /// Get the length of the font family name where the current position is at. + /// </summary> + /// <param name="currentPosition">The current text position.</param> + /// <param name="nameLength">Size of the character array in character count not including the terminated NULL character.</param> + /// <param name="textRange">The position range of the current format.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetFontFamilyNameLength)( + UINT32 currentPosition, + __out UINT32* nameLength, + __out_opt DWRITE_TEXT_RANGE* textRange = NULL + ) PURE; + + /// <summary> + /// Copy the font family name where the current position is at. + /// </summary> + /// <param name="currentPosition">The current text position.</param> + /// <param name="fontFamilyName">Character array that receives the current font family name</param> + /// <param name="nameSize">Size of the character array in character count including the terminated NULL character.</param> + /// <param name="textRange">The position range of the current format.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetFontFamilyName)( + UINT32 currentPosition, + __out_ecount_z(nameSize) WCHAR* fontFamilyName, + UINT32 nameSize, + __out_opt DWRITE_TEXT_RANGE* textRange = NULL + ) PURE; + + /// <summary> + /// Get the font weight where the current position is at. + /// </summary> + /// <param name="currentPosition">The current text position.</param> + /// <param name="fontWeight">The current font weight</param> + /// <param name="textRange">The position range of the current format.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetFontWeight)( + UINT32 currentPosition, + __out DWRITE_FONT_WEIGHT* fontWeight, + __out_opt DWRITE_TEXT_RANGE* textRange = NULL + ) PURE; + + /// <summary> + /// Get the font style where the current position is at. + /// </summary> + /// <param name="currentPosition">The current text position.</param> + /// <param name="fontStyle">The current font style</param> + /// <param name="textRange">The position range of the current format.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetFontStyle)( + UINT32 currentPosition, + __out DWRITE_FONT_STYLE* fontStyle, + __out_opt DWRITE_TEXT_RANGE* textRange = NULL + ) PURE; + + /// <summary> + /// Get the font stretch where the current position is at. + /// </summary> + /// <param name="currentPosition">The current text position.</param> + /// <param name="fontStretch">The current font stretch</param> + /// <param name="textRange">The position range of the current format.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetFontStretch)( + UINT32 currentPosition, + __out DWRITE_FONT_STRETCH* fontStretch, + __out_opt DWRITE_TEXT_RANGE* textRange = NULL + ) PURE; + + /// <summary> + /// Get the font em height where the current position is at. + /// </summary> + /// <param name="currentPosition">The current text position.</param> + /// <param name="fontSize">The current font em height</param> + /// <param name="textRange">The position range of the current format.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetFontSize)( + UINT32 currentPosition, + __out FLOAT* fontSize, + __out_opt DWRITE_TEXT_RANGE* textRange = NULL + ) PURE; + + /// <summary> + /// Get the underline presence where the current position is at. + /// </summary> + /// <param name="currentPosition">The current text position.</param> + /// <param name="hasUnderline">The Boolean flag indicates whether text is underlined.</param> + /// <param name="textRange">The position range of the current format.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetUnderline)( + UINT32 currentPosition, + __out BOOL* hasUnderline, + __out_opt DWRITE_TEXT_RANGE* textRange = NULL + ) PURE; + + /// <summary> + /// Get the strikethrough presence where the current position is at. + /// </summary> + /// <param name="currentPosition">The current text position.</param> + /// <param name="hasStrikethrough">The Boolean flag indicates whether text has strikethrough.</param> + /// <param name="textRange">The position range of the current format.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetStrikethrough)( + UINT32 currentPosition, + __out BOOL* hasStrikethrough, + __out_opt DWRITE_TEXT_RANGE* textRange = NULL + ) PURE; + + /// <summary> + /// Get the application-defined drawing effect where the current position is at. + /// </summary> + /// <param name="currentPosition">The current text position.</param> + /// <param name="drawingEffect">The current application-defined drawing effect.</param> + /// <param name="textRange">The position range of the current format.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetDrawingEffect)( + UINT32 currentPosition, + __out IUnknown** drawingEffect, + __out_opt DWRITE_TEXT_RANGE* textRange = NULL + ) PURE; + + /// <summary> + /// Get the inline object at the given position. + /// </summary> + /// <param name="currentPosition">The given text position.</param> + /// <param name="inlineObject">The inline object.</param> + /// <param name="textRange">The position range of the current format.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetInlineObject)( + UINT32 currentPosition, + __out IDWriteInlineObject** inlineObject, + __out_opt DWRITE_TEXT_RANGE* textRange = NULL + ) PURE; + + /// <summary> + /// Get the typography setting where the current position is at. + /// </summary> + /// <param name="currentPosition">The current text position.</param> + /// <param name="typography">The current typography setting.</param> + /// <param name="textRange">The position range of the current format.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetTypography)( + UINT32 currentPosition, + __out IDWriteTypography** typography, + __out_opt DWRITE_TEXT_RANGE* textRange = NULL + ) PURE; + + /// <summary> + /// Get the length of the locale name where the current position is at. + /// </summary> + /// <param name="currentPosition">The current text position.</param> + /// <param name="nameLength">Size of the character array in character count not including the terminated NULL character.</param> + /// <param name="textRange">The position range of the current format.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetLocaleNameLength)( + UINT32 currentPosition, + __out UINT32* nameLength, + __out_opt DWRITE_TEXT_RANGE* textRange = NULL + ) PURE; + + /// <summary> + /// Get the locale name where the current position is at. + /// </summary> + /// <param name="currentPosition">The current text position.</param> + /// <param name="localeName">Character array that receives the current locale name</param> + /// <param name="nameSize">Size of the character array in character count including the terminated NULL character.</param> + /// <param name="textRange">The position range of the current format.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetLocaleName)( + UINT32 currentPosition, + __out_ecount_z(nameSize) WCHAR* localeName, + UINT32 nameSize, + __out_opt DWRITE_TEXT_RANGE* textRange = NULL + ) PURE; + + /// <summary> + /// Initiate drawing of the text. + /// </summary> + /// <param name="clientDrawingContext">An application defined value + /// included in rendering callbacks.</param> + /// <param name="renderer">The set of application-defined callbacks that do + /// the actual rendering.</param> + /// <param name="originX">X-coordinate of the layout's left side.</param> + /// <param name="originY">Y-coordinate of the layout's top side.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(Draw)( + __maybenull void* clientDrawingContext, + IDWriteTextRenderer* renderer, + FLOAT originX, + FLOAT originY + ) PURE; + + /// <summary> + /// GetLineMetrics returns properties of each line. + /// </summary> + /// <param name="lineMetrics">The array to fill with line information.</param> + /// <param name="maxLineCount">The maximum size of the lineMetrics array.</param> + /// <param name="actualLineCount">The actual size of the lineMetrics + /// array that is needed.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + /// <remarks> + /// 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. + /// </remarks> + STDMETHOD(GetLineMetrics)( + __out_ecount_opt(maxLineCount) DWRITE_LINE_METRICS* lineMetrics, + UINT32 maxLineCount, + __out UINT32* actualLineCount + ) PURE; + + /// <summary> + /// GetMetrics retrieves overall metrics for the formatted string. + /// </summary> + /// <param name="textMetrics">The returned metrics.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + /// <remarks> + /// 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. + /// </remarks> + STDMETHOD(GetMetrics)( + __out DWRITE_TEXT_METRICS* textMetrics + ) PURE; + + /// <summary> + /// GetOverhangMetrics returns the overhangs (in DIPs) of the layout and all + /// objects contained in it, including text glyphs and inline objects. + /// </summary> + /// <param name="overhangs">Overshoots of visible extents (in DIPs) outside the layout.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + /// <remarks> + /// 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. + /// </remarks> + STDMETHOD(GetOverhangMetrics)( + __out DWRITE_OVERHANG_METRICS* overhangs + ) PURE; + + /// <summary> + /// Retrieve logical properties and measurement of each cluster. + /// </summary> + /// <param name="clusterMetrics">The array to fill with cluster information.</param> + /// <param name="maxClusterCount">The maximum size of the clusterMetrics array.</param> + /// <param name="actualClusterCount">The actual size of the clusterMetrics array that is needed.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + /// <remarks> + /// 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. + /// </remarks> + STDMETHOD(GetClusterMetrics)( + __out_ecount_opt(maxClusterCount) DWRITE_CLUSTER_METRICS* clusterMetrics, + UINT32 maxClusterCount, + __out UINT32* actualClusterCount + ) PURE; + + /// <summary> + /// Determines the minimum possible width the layout can be set to without + /// emergency breaking between the characters of whole words. + /// </summary> + /// <param name="minWidth">Minimum width.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(DetermineMinWidth)( + __out FLOAT* minWidth + ) PURE; + + /// <summary> + /// 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. + /// </summary> + /// <param name="pointX">X coordinate to hit-test, relative to the top-left location of the layout box.</param> + /// <param name="pointY">Y coordinate to hit-test, relative to the top-left location of the layout box.</param> + /// <param name="isTrailingHit">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. </param> + /// <param name="isInside">Output flag indicating whether the hit-test location is inside the text string. + /// When false, the position nearest the text's edge is returned.</param> + /// <param name="hitTestMetrics">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.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(HitTestPoint)( + FLOAT pointX, + FLOAT pointY, + __out BOOL* isTrailingHit, + __out BOOL* isInside, + __out DWRITE_HIT_TEST_METRICS* hitTestMetrics + ) PURE; + + /// <summary> + /// 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. + /// </summary> + /// <param name="textPosition">Text position to get the coordinate of.</param> + /// <param name="isTrailingHit">Flag indicating whether the location is of the leading or the trailing side of the specified text position. </param> + /// <param name="pointX">Output caret X, relative to the top-left of the layout box.</param> + /// <param name="pointY">Output caret Y, relative to the top-left of the layout box.</param> + /// <param name="hitTestMetrics">Output geometry fully enclosing the specified text position.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + /// <remarks> + /// 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. + /// </remarks> + STDMETHOD(HitTestTextPosition)( + UINT32 textPosition, + BOOL isTrailingHit, + __out FLOAT* pointX, + __out FLOAT* pointY, + __out DWRITE_HIT_TEST_METRICS* hitTestMetrics + ) PURE; + + /// <summary> + /// 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. + /// </summary> + /// <param name="textPosition">First text position of the specified range.</param> + /// <param name="textLength">Number of positions of the specified range.</param> + /// <param name="originX">Offset of the X origin (left of the layout box) which is added to each of the hit-test metrics returned.</param> + /// <param name="originY">Offset of the Y origin (top of the layout box) which is added to each of the hit-test metrics returned.</param> + /// <param name="hitTestMetrics">Pointer to a buffer of the output geometry fully enclosing the specified position range.</param> + /// <param name="maxHitTestMetricsCount">Maximum number of distinct metrics it could hold in its buffer memory.</param> + /// <param name="actualHitTestMetricsCount">Actual number of metrics returned or needed.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + /// <remarks> + /// 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. + /// </remarks> + 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; +}; + +/// <summary> +/// Encapsulates a 32-bit device independent bitmap and device context, which can be used for rendering glyphs. +/// </summary> +interface DWRITE_DECLARE_INTERFACE("5e5a32a3-8dff-4773-9ff6-0696eab77267") IDWriteBitmapRenderTarget : public IUnknown +{ + /// <summary> + /// Draws a run of glyphs to the bitmap. + /// </summary> + /// <param name="baselineOriginX">Horizontal position of the baseline origin, in DIPs, relative to the upper-left corner of the DIB.</param> + /// <param name="baselineOriginY">Vertical position of the baseline origin, in DIPs, relative to the upper-left corner of the DIB.</param> + /// <param name="measuringMode">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. + /// </param> + /// <param name="glyphRun">Structure containing the properties of the glyph run.</param> + /// <param name="renderingParams">Object that controls rendering behavior.</param> + /// <param name="textColor">Specifies the foreground color of the text.</param> + /// <param name="blackBoxRect">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.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + 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; + + /// <summary> + /// Gets a handle to the memory device context. + /// </summary> + /// <returns> + /// Returns the device context handle. + /// </returns> + /// <remarks> + /// 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. + /// </remarks> + STDMETHOD_(HDC, GetMemoryDC)() PURE; + + /// <summary> + /// 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. + /// </summary> + /// <returns> + /// Returns the number of bitmap pixels per DIP. + /// </returns> + STDMETHOD_(FLOAT, GetPixelsPerDip)() PURE; + + /// <summary> + /// 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. + /// </summary> + /// <param name="pixelsPerDip">Specifies the number of pixels per DIP.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(SetPixelsPerDip)( + FLOAT pixelsPerDip + ) PURE; + + /// <summary> + /// 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. + /// </summary> + /// <param name="transform">Receives the transform.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetCurrentTransform)( + __out DWRITE_MATRIX* transform + ) PURE; + + /// <summary> + /// Sets the transform that maps abstract coordinate to DIPs. This does not affect the world + /// transform of the underlying device context. + /// </summary> + /// <param name="transform">Specifies the new transform. This parameter can be NULL, in which + /// case the identity transform is implied.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(SetCurrentTransform)( + __in_opt DWRITE_MATRIX const* transform + ) PURE; + + /// <summary> + /// Gets the dimensions of the bitmap. + /// </summary> + /// <param name="size">Receives the size of the bitmap in pixels.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetSize)( + __out SIZE* size + ) PURE; + + /// <summary> + /// Resizes the bitmap. + /// </summary> + /// <param name="width">New bitmap width, in pixels.</param> + /// <param name="height">New bitmap height, in pixels.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(Resize)( + UINT32 width, + UINT32 height + ) PURE; +}; + +/// <summary> +/// The GDI interop interface provides interoperability with GDI. +/// </summary> +interface DWRITE_DECLARE_INTERFACE("1edd9491-9853-4299-898f-6432983b6f3a") IDWriteGdiInterop : public IUnknown +{ + /// <summary> + /// Creates a font object that matches the properties specified by the LOGFONT structure. + /// </summary> + /// <param name="logFont">Structure containing a GDI-compatible font description.</param> + /// <param name="font">Receives a newly created font object if successful, or NULL in case of error.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(CreateFontFromLOGFONT)( + __in LOGFONTW const* logFont, + __out IDWriteFont** font + ) PURE; + + /// <summary> + /// Initializes a LOGFONT structure based on the GDI-compatible properties of the specified font. + /// </summary> + /// <param name="font">Specifies a font in the system font collection.</param> + /// <param name="logFont">Structure that receives a GDI-compatible font description.</param> + /// <param name="isSystemFont">Contains TRUE if the specified font object is part of the system font collection + /// or FALSE otherwise.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(ConvertFontToLOGFONT)( + IDWriteFont* font, + __out LOGFONTW* logFont, + __out BOOL* isSystemFont + ) PURE; + + /// <summary> + /// Initializes a LOGFONT structure based on the GDI-compatible properties of the specified font. + /// </summary> + /// <param name="font">Specifies a font face.</param> + /// <param name="logFont">Structure that receives a GDI-compatible font description.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(ConvertFontFaceToLOGFONT)( + IDWriteFontFace* font, + __out LOGFONTW* logFont + ) PURE; + + /// <summary> + /// Creates a font face object that corresponds to the currently selected HFONT. + /// </summary> + /// <param name="hdc">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.</param> + /// <param name="fontFace">Contains the newly created font face object, or NULL in case of failure.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(CreateFontFaceFromHdc)( + HDC hdc, + __out IDWriteFontFace** fontFace + ) PURE; + + /// <summary> + /// Creates an object that encapsulates a bitmap and memory DC which can be used for rendering glyphs. + /// </summary> + /// <param name="hdc">Optional device context used to create a compatible memory DC.</param> + /// <param name="width">Width of the bitmap.</param> + /// <param name="height">Height of the bitmap.</param> + /// <param name="renderTarget">Receives a pointer to the newly created render target.</param> + STDMETHOD(CreateBitmapRenderTarget)( + __in_opt HDC hdc, + UINT32 width, + UINT32 height, + __out IDWriteBitmapRenderTarget** renderTarget + ) PURE; +}; + +/// <summary> +/// 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. +/// </summary> +enum DWRITE_TEXTURE_TYPE +{ + /// <summary> + /// 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. + /// </summary> + DWRITE_TEXTURE_ALIASED_1x1, + + /// <summary> + /// 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. + /// </summary> + DWRITE_TEXTURE_CLEARTYPE_3x1 +}; + +/// <summary> +/// Maximum alpha value in a texture returned by IDWriteGlyphRunAnalysis::CreateAlphaTexture. +/// </summary> +#define DWRITE_ALPHA_MAX 255 + +/// <summary> +/// Interface that encapsulates information used to render a glyph run. +/// </summary> +interface DWRITE_DECLARE_INTERFACE("7d97dbf7-e085-42d4-81e3-6a883bded118") IDWriteGlyphRunAnalysis : public IUnknown +{ + /// <summary> + /// Gets the bounding rectangle of the physical pixels affected by the glyph run. + /// </summary> + /// <param name="textureType">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.</param> + /// <param name="textureBounds">Receives the bounding rectangle, or an empty rectangle if there are no glyphs + /// if the specified type.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetAlphaTextureBounds)( + DWRITE_TEXTURE_TYPE textureType, + __out RECT* textureBounds + ) PURE; + + /// <summary> + /// Creates an alpha texture of the specified type. + /// </summary> + /// <param name="textureType">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.</param> + /// <param name="textureBounds">Specifies the bounding rectangle of the texture, which can be different than + /// the bounding rectangle returned by GetAlphaTextureBounds.</param> + /// <param name="alphaValues">Receives the array of alpha values.</param> + /// <param name="bufferSize">Size of the alphaValues array. The minimum size depends on the dimensions of the + /// rectangle and the type of texture requested.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(CreateAlphaTexture)( + DWRITE_TEXTURE_TYPE textureType, + __in RECT const* textureBounds, + __out_bcount(bufferSize) BYTE* alphaValues, + UINT32 bufferSize + ) PURE; + + /// <summary> + /// Gets properties required for ClearType blending. + /// </summary> + /// <param name="renderingParams">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.</param> + /// <param name="blendGamma">Receives the gamma value to use for gamma correction.</param> + /// <param name="blendEnhancedContrast">Receives the enhanced contrast value.</param> + /// <param name="blendClearTypeLevel">Receives the ClearType level.</param> + STDMETHOD(GetAlphaBlendParams)( + IDWriteRenderingParams* renderingParams, + __out FLOAT* blendGamma, + __out FLOAT* blendEnhancedContrast, + __out FLOAT* blendClearTypeLevel + ) PURE; +}; + +/// <summary> +/// The root factory interface for all DWrite objects. +/// </summary> +interface DWRITE_DECLARE_INTERFACE("b859ee5a-d838-4b5b-a2e8-1adc7d93db48") IDWriteFactory : public IUnknown +{ + /// <summary> + /// Gets a font collection representing the set of installed fonts. + /// </summary> + /// <param name="fontCollection">Receives a pointer to the system font collection object, or NULL in case of failure.</param> + /// <param name="checkForUpdates">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.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetSystemFontCollection)( + __out IDWriteFontCollection** fontCollection, + BOOL checkForUpdates = FALSE + ) PURE; + + /// <summary> + /// Creates a font collection using a custom font collection loader. + /// </summary> + /// <param name="collectionLoader">Application-defined font collection loader, which must have been previously + /// registered using RegisterFontCollectionLoader.</param> + /// <param name="collectionKey">Key used by the loader to identify a collection of font files.</param> + /// <param name="collectionKeySize">Size in bytes of the collection key.</param> + /// <param name="fontCollection">Receives a pointer to the system font collection object, or NULL in case of failure.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(CreateCustomFontCollection)( + IDWriteFontCollectionLoader* collectionLoader, + __in_bcount(collectionKeySize) void const* collectionKey, + UINT32 collectionKeySize, + __out IDWriteFontCollection** fontCollection + ) PURE; + + /// <summary> + /// Registers a custom font collection loader with the factory object. + /// </summary> + /// <param name="fontCollectionLoader">Application-defined font collection loader.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(RegisterFontCollectionLoader)( + IDWriteFontCollectionLoader* fontCollectionLoader + ) PURE; + + /// <summary> + /// Unregisters a custom font collection loader that was previously registered using RegisterFontCollectionLoader. + /// </summary> + /// <param name="fontCollectionLoader">Application-defined font collection loader.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(UnregisterFontCollectionLoader)( + IDWriteFontCollectionLoader* fontCollectionLoader + ) PURE; + + /// <summary> + /// CreateFontFileReference creates a font file reference object from a local font file. + /// </summary> + /// <param name="filePath">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.</param> + /// <param name="lastWriteTime">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.</param> + /// <param name="fontFile">Contains newly created font file reference object, or NULL in case of failure.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(CreateFontFileReference)( + __in_z WCHAR const* filePath, + __in_opt FILETIME const* lastWriteTime, + __out IDWriteFontFile** fontFile + ) PURE; + + /// <summary> + /// 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. + /// </summary> + /// <param name="fontFileReferenceKey">Font file reference key that uniquely identifies the font file resource + /// during the lifetime of fontFileLoader.</param> + /// <param name="fontFileReferenceKeySize">Size of font file reference key in bytes.</param> + /// <param name="fontFileLoader">Font file loader that will be used by the font system to load data from the file identified by + /// fontFileReferenceKey.</param> + /// <param name="fontFile">Contains the newly created font file object, or NULL in case of failure.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + /// <remarks> + /// 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. + /// </remarks> + STDMETHOD(CreateCustomFontFileReference)( + __in_bcount(fontFileReferenceKeySize) void const* fontFileReferenceKey, + UINT32 fontFileReferenceKeySize, + IDWriteFontFileLoader* fontFileLoader, + __out IDWriteFontFile** fontFile + ) PURE; + + /// <summary> + /// Creates a font face object. + /// </summary> + /// <param name="fontFaceType">The file format of the font face.</param> + /// <param name="numberOfFiles">The number of font files require to represent the font face.</param> + /// <param name="fontFiles">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.</param> + /// <param name="faceIndex">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.</param> + /// <param name="fontFaceSimulationFlags">Font face simulation flags for algorithmic emboldening and italicization.</param> + /// <param name="fontFace">Contains the newly created font face object, or NULL in case of failure.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + 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; + + /// <summary> + /// Creates a rendering parameters object with default settings for the primary monitor. + /// </summary> + /// <param name="renderingParams">Holds the newly created rendering parameters object, or NULL in case of failure.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(CreateRenderingParams)( + __out IDWriteRenderingParams** renderingParams + ) PURE; + + /// <summary> + /// Creates a rendering parameters object with default settings for the specified monitor. + /// </summary> + /// <param name="monitor">The monitor to read the default values from.</param> + /// <param name="renderingParams">Holds the newly created rendering parameters object, or NULL in case of failure.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(CreateMonitorRenderingParams)( + HMONITOR monitor, + __out IDWriteRenderingParams** renderingParams + ) PURE; + + /// <summary> + /// Creates a rendering parameters object with the specified properties. + /// </summary> + /// <param name="gamma">The gamma value used for gamma correction, which must be greater than zero and cannot exceed 256.</param> + /// <param name="enhancedContrast">The amount of contrast enhancement, zero or greater.</param> + /// <param name="clearTypeLevel">The degree of ClearType level, from 0.0f (no ClearType) to 1.0f (full ClearType).</param> + /// <param name="pixelGeometry">The geometry of a device pixel.</param> + /// <param name="renderingMode">Method of rendering glyphs. In most cases, this should be DWRITE_RENDERING_MODE_DEFAULT to automatically use an appropriate mode.</param> + /// <param name="renderingParams">Holds the newly created rendering parameters object, or NULL in case of failure.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(CreateCustomRenderingParams)( + FLOAT gamma, + FLOAT enhancedContrast, + FLOAT clearTypeLevel, + DWRITE_PIXEL_GEOMETRY pixelGeometry, + DWRITE_RENDERING_MODE renderingMode, + __out IDWriteRenderingParams** renderingParams + ) PURE; + + /// <summary> + /// Registers a font file loader with DirectWrite. + /// </summary> + /// <param name="fontFileLoader">Pointer to the implementation of the IDWriteFontFileLoader for a particular file resource type.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + /// <remarks> + /// 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. + /// </remarks> + STDMETHOD(RegisterFontFileLoader)( + IDWriteFontFileLoader* fontFileLoader + ) PURE; + + /// <summary> + /// Unregisters a font file loader that was previously registered with the DirectWrite font system using RegisterFontFileLoader. + /// </summary> + /// <param name="fontFileLoader">Pointer to the file loader that was previously registered with the DirectWrite font system using RegisterFontFileLoader.</param> + /// <returns> + /// 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. + /// </returns> + /// <remarks> + /// 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. + /// </remarks> + STDMETHOD(UnregisterFontFileLoader)( + IDWriteFontFileLoader* fontFileLoader + ) PURE; + + /// <summary> + /// Create a text format object used for text layout. + /// </summary> + /// <param name="fontFamilyName">Name of the font family</param> + /// <param name="fontCollection">Font collection. NULL indicates the system font collection.</param> + /// <param name="fontWeight">Font weight</param> + /// <param name="fontStyle">Font style</param> + /// <param name="fontStretch">Font stretch</param> + /// <param name="fontSize">Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.</param> + /// <param name="localeName">Locale name</param> + /// <param name="textFormat">Contains newly created text format object, or NULL in case of failure.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + 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; + + /// <summary> + /// Create a typography object used in conjunction with text format for text layout. + /// </summary> + /// <param name="typography">Contains newly created typography object, or NULL in case of failure.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(CreateTypography)( + __out IDWriteTypography** typography + ) PURE; + + /// <summary> + /// Create an object used for interoperability with GDI. + /// </summary> + /// <param name="gdiInterop">Receives the GDI interop object if successful, or NULL in case of failure.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(GetGdiInterop)( + __out IDWriteGdiInterop** gdiInterop + ) PURE; + + /// <summary> + /// CreateTextLayout takes a string, format, and associated constraints + /// and produces and object representing the fully analyzed + /// and formatted result. + /// </summary> + /// <param name="string">The string to layout.</param> + /// <param name="stringLength">The length of the string.</param> + /// <param name="textFormat">The format to apply to the string.</param> + /// <param name="maxWidth">Width of the layout box.</param> + /// <param name="maxHeight">Height of the layout box.</param> + /// <param name="textLayout">The resultant object.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(CreateTextLayout)( + __in_ecount(stringLength) WCHAR const* string, + UINT32 stringLength, + IDWriteTextFormat* textFormat, + FLOAT maxWidth, + FLOAT maxHeight, + __out IDWriteTextLayout** textLayout + ) PURE; + + /// <summary> + /// 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. + /// </summary> + /// <param name="string">The string to layout.</param> + /// <param name="stringLength">The length of the string.</param> + /// <param name="textFormat">The format to apply to the string.</param> + /// <param name="layoutWidth">Width of the layout box.</param> + /// <param name="layoutHeight">Height of the layout box.</param> + /// <param name="pixelsPerDip">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.</param> + /// <param name="transform">Optional transform applied to the glyphs and their positions. This transform is applied after the + /// scaling specified the font size and pixelsPerDip.</param> + /// <param name="useGdiNatural"> + /// 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. + /// </param> + /// <param name="textLayout">The resultant object.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + 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; + + /// <summary> + /// 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. + /// </summary> + /// <param name="textFormat">Text format used as a template for the omission sign.</param> + /// <param name="trimmingSign">Created omission sign.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(CreateEllipsisTrimmingSign)( + IDWriteTextFormat* textFormat, + __out IDWriteInlineObject** trimmingSign + ) PURE; + + /// <summary> + /// Return an interface to perform text analysis with. + /// </summary> + /// <param name="textAnalyzer">The resultant object.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + STDMETHOD(CreateTextAnalyzer)( + __out IDWriteTextAnalyzer** textAnalyzer + ) PURE; + + /// <summary> + /// 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). + /// </summary> + /// <param name="substitutionMethod">Method of number substitution to use.</param> + /// <param name="localeName">Which locale to obtain the digits from.</param> + /// <param name="ignoreUserOverride">Ignore the user's settings and use the locale defaults</param> + /// <param name="numberSubstitution">Receives a pointer to the newly created object.</param> + STDMETHOD(CreateNumberSubstitution)( + __in DWRITE_NUMBER_SUBSTITUTION_METHOD substitutionMethod, + __in_z WCHAR const* localeName, + __in BOOL ignoreUserOverride, + __out IDWriteNumberSubstitution** numberSubstitution + ) PURE; + + /// <summary> + /// Creates a glyph run analysis object, which encapsulates information + /// used to render a glyph run. + /// </summary> + /// <param name="glyphRun">Structure specifying the properties of the glyph run.</param> + /// <param name="pixelsPerDip">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.</param> + /// <param name="transform">Optional transform applied to the glyphs and their positions. This transform is applied after the + /// scaling specified the emSize and pixelsPerDip.</param> + /// <param name="renderingMode">Specifies the rendering mode, which must be one of the raster rendering modes (i.e., not default + /// and not outline).</param> + /// <param name="measuringMode">Specifies the method to measure glyphs.</param> + /// <param name="baselineOriginX">Horizontal position of the baseline origin, in DIPs.</param> + /// <param name="baselineOriginY">Vertical position of the baseline origin, in DIPs.</param> + /// <param name="glyphRunAnalysis">Receives a pointer to the newly created object.</param> + /// <returns> + /// Standard HRESULT error code. + /// </returns> + 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 + +/// <summary> +/// Creates a DirectWrite factory object that is used for subsequent creation of individual DirectWrite objects. +/// </summary> +/// <param name="factoryType">Identifies whether the factory object will be shared or isolated.</param> +/// <param name="iid">Identifies the DirectWrite factory interface, such as __uuidof(IDWriteFactory).</param> +/// <param name="factory">Receives the DirectWrite factory object.</param> +/// <returns> +/// Standard HRESULT error code. +/// </returns> +/// <remarks> +/// 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. +/// </remarks> +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) + +/// <summary> +/// Indicates an error in an input file such as a font file. +/// </summary> +#define DWRITE_E_FILEFORMAT MAKE_DWRITE_HR_ERR(0x000) + +/// <summary> +/// Indicates an error originating in DirectWrite code, which is not expected to occur but is safe to recover from. +/// </summary> +#define DWRITE_E_UNEXPECTED MAKE_DWRITE_HR_ERR(0x001) + +/// <summary> +/// Indicates the specified font does not exist. +/// </summary> +#define DWRITE_E_NOFONT MAKE_DWRITE_HR_ERR(0x002) + +/// <summary> +/// A font file could not be opened because the file, directory, network location, drive, or other storage +/// location does not exist or is unavailable. +/// </summary> +#define DWRITE_E_FILENOTFOUND MAKE_DWRITE_HR_ERR(0x003) + +/// <summary> +/// A font file exists but could not be opened due to access denied, sharing violation, or similar error. +/// </summary> +#define DWRITE_E_FILEACCESS MAKE_DWRITE_HR_ERR(0x004) + +/// <summary> +/// A font collection is obsolete due to changes in the system. +/// </summary> +#define DWRITE_E_FONTCOLLECTIONOBSOLETE MAKE_DWRITE_HR_ERR(0x005) + +/// <summary> +/// The given interface is already registered. +/// </summary> +#define DWRITE_E_ALREADYREGISTERED MAKE_DWRITE_HR_ERR(0x006) + +#endif /* DWRITE_H_INCLUDED */ |