• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 //+--------------------------------------------------------------------------
2 //
3 //  Copyright (c) Microsoft Corporation.  All rights reserved.
4 //
5 //  Abstract:
6 //     DirectX Typography Services public API definitions.
7 //
8 //----------------------------------------------------------------------------
9 
10 #ifndef DWRITE_H_INCLUDED
11 #define DWRITE_H_INCLUDED
12 
13 #if _MSC_VER > 1000
14 #pragma once
15 #endif
16 
17 #ifndef DWRITE_NO_WINDOWS_H
18 
19 #include "specstrings.h"
20 #include "unknwn.h"
21 
22 #endif // DWRITE_NO_WINDOWS_H
23 
24 #include "dcommon.h"
25 
26 #if _FX_COMPILER_ == _FX_VC6_
27 typedef signed char         INT8, *PINT8;
28 typedef signed short        INT16, *PINT16;
29 typedef signed int          INT32, *PINT32;
30 typedef signed __int64      INT64, *PINT64;
31 typedef unsigned char       UINT8, *PUINT8;
32 typedef unsigned short      UINT16, *PUINT16;
33 typedef unsigned int        UINT32, *PUINT32;
34 typedef unsigned __int64    UINT64, *PUINT64;
35 #endif
36 
37 #ifndef DWRITE_DECLARE_INTERFACE
38 #define DWRITE_DECLARE_INTERFACE(iid) DECLSPEC_UUID(iid) DECLSPEC_NOVTABLE
39 #endif
40 
41 #ifndef DWRITE_EXPORT
42 #define DWRITE_EXPORT __declspec(dllimport) WINAPI
43 #endif
44 
45 /// <summary>
46 /// The type of a font represented by a single font file.
47 /// Font formats that consist of multiple files, e.g. Type 1 .PFM and .PFB, have
48 /// separate enum values for each of the file type.
49 /// </summary>
50 enum DWRITE_FONT_FILE_TYPE
51 {
52     /// <summary>
53     /// Font type is not recognized by the DirectWrite font system.
54     /// </summary>
55     DWRITE_FONT_FILE_TYPE_UNKNOWN,
56 
57     /// <summary>
58     /// OpenType font with CFF outlines.
59     /// </summary>
60     DWRITE_FONT_FILE_TYPE_CFF,
61 
62     /// <summary>
63     /// OpenType font with TrueType outlines.
64     /// </summary>
65     DWRITE_FONT_FILE_TYPE_TRUETYPE,
66 
67     /// <summary>
68     /// OpenType font that contains a TrueType collection.
69     /// </summary>
70     DWRITE_FONT_FILE_TYPE_TRUETYPE_COLLECTION,
71 
72     /// <summary>
73     /// Type 1 PFM font.
74     /// </summary>
75     DWRITE_FONT_FILE_TYPE_TYPE1_PFM,
76 
77     /// <summary>
78     /// Type 1 PFB font.
79     /// </summary>
80     DWRITE_FONT_FILE_TYPE_TYPE1_PFB,
81 
82     /// <summary>
83     /// Vector .FON font.
84     /// </summary>
85     DWRITE_FONT_FILE_TYPE_VECTOR,
86 
87     /// <summary>
88     /// Bitmap .FON font.
89     /// </summary>
90     DWRITE_FONT_FILE_TYPE_BITMAP
91 };
92 
93 /// <summary>
94 /// The file format of a complete font face.
95 /// Font formats that consist of multiple files, e.g. Type 1 .PFM and .PFB, have
96 /// a single enum entry.
97 /// </summary>
98 enum DWRITE_FONT_FACE_TYPE
99 {
100     /// <summary>
101     /// OpenType font face with CFF outlines.
102     /// </summary>
103     DWRITE_FONT_FACE_TYPE_CFF,
104 
105     /// <summary>
106     /// OpenType font face with TrueType outlines.
107     /// </summary>
108     DWRITE_FONT_FACE_TYPE_TRUETYPE,
109 
110     /// <summary>
111     /// OpenType font face that is a part of a TrueType collection.
112     /// </summary>
113     DWRITE_FONT_FACE_TYPE_TRUETYPE_COLLECTION,
114 
115     /// <summary>
116     /// A Type 1 font face.
117     /// </summary>
118     DWRITE_FONT_FACE_TYPE_TYPE1,
119 
120     /// <summary>
121     /// A vector .FON format font face.
122     /// </summary>
123     DWRITE_FONT_FACE_TYPE_VECTOR,
124 
125     /// <summary>
126     /// A bitmap .FON format font face.
127     /// </summary>
128     DWRITE_FONT_FACE_TYPE_BITMAP,
129 
130     /// <summary>
131     /// Font face type is not recognized by the DirectWrite font system.
132     /// </summary>
133     DWRITE_FONT_FACE_TYPE_UNKNOWN
134 };
135 
136 /// <summary>
137 /// Specifies algorithmic style simulations to be applied to the font face.
138 /// Bold and oblique simulations can be combined via bitwise OR operation.
139 /// </summary>
140 enum DWRITE_FONT_SIMULATIONS
141 {
142     /// <summary>
143     /// No simulations are performed.
144     /// </summary>
145     DWRITE_FONT_SIMULATIONS_NONE    = 0x0000,
146 
147     /// <summary>
148     /// Algorithmic emboldening is performed.
149     /// </summary>
150     DWRITE_FONT_SIMULATIONS_BOLD    = 0x0001,
151 
152     /// <summary>
153     /// Algorithmic italicization is performed.
154     /// </summary>
155     DWRITE_FONT_SIMULATIONS_OBLIQUE = 0x0002
156 };
157 
158 #ifdef DEFINE_ENUM_FLAG_OPERATORS
159 DEFINE_ENUM_FLAG_OPERATORS(DWRITE_FONT_SIMULATIONS);
160 #endif
161 
162 /// <summary>
163 /// The font weight enumeration describes common values for degree of blackness or thickness of strokes of characters in a font.
164 /// Font weight values less than 1 or greater than 999 are considered to be invalid, and they are rejected by font API functions.
165 /// </summary>
166 enum DWRITE_FONT_WEIGHT
167 {
168     /// <summary>
169     /// Predefined font weight : Thin (100).
170     /// </summary>
171     DWRITE_FONT_WEIGHT_THIN = 100,
172 
173     /// <summary>
174     /// Predefined font weight : Extra-light (200).
175     /// </summary>
176     DWRITE_FONT_WEIGHT_EXTRA_LIGHT = 200,
177 
178     /// <summary>
179     /// Predefined font weight : Ultra-light (200).
180     /// </summary>
181     DWRITE_FONT_WEIGHT_ULTRA_LIGHT = 200,
182 
183     /// <summary>
184     /// Predefined font weight : Light (300).
185     /// </summary>
186     DWRITE_FONT_WEIGHT_LIGHT = 300,
187 
188     /// <summary>
189     /// Predefined font weight : Normal (400).
190     /// </summary>
191     DWRITE_FONT_WEIGHT_NORMAL = 400,
192 
193     /// <summary>
194     /// Predefined font weight : Regular (400).
195     /// </summary>
196     DWRITE_FONT_WEIGHT_REGULAR = 400,
197 
198     /// <summary>
199     /// Predefined font weight : Medium (500).
200     /// </summary>
201     DWRITE_FONT_WEIGHT_MEDIUM = 500,
202 
203     /// <summary>
204     /// Predefined font weight : Demi-bold (600).
205     /// </summary>
206     DWRITE_FONT_WEIGHT_DEMI_BOLD = 600,
207 
208     /// <summary>
209     /// Predefined font weight : Semi-bold (600).
210     /// </summary>
211     DWRITE_FONT_WEIGHT_SEMI_BOLD = 600,
212 
213     /// <summary>
214     /// Predefined font weight : Bold (700).
215     /// </summary>
216     DWRITE_FONT_WEIGHT_BOLD = 700,
217 
218     /// <summary>
219     /// Predefined font weight : Extra-bold (800).
220     /// </summary>
221     DWRITE_FONT_WEIGHT_EXTRA_BOLD = 800,
222 
223     /// <summary>
224     /// Predefined font weight : Ultra-bold (800).
225     /// </summary>
226     DWRITE_FONT_WEIGHT_ULTRA_BOLD = 800,
227 
228     /// <summary>
229     /// Predefined font weight : Black (900).
230     /// </summary>
231     DWRITE_FONT_WEIGHT_BLACK = 900,
232 
233     /// <summary>
234     /// Predefined font weight : Heavy (900).
235     /// </summary>
236     DWRITE_FONT_WEIGHT_HEAVY = 900,
237 
238     /// <summary>
239     /// Predefined font weight : Extra-black (950).
240     /// </summary>
241     DWRITE_FONT_WEIGHT_EXTRA_BLACK = 950,
242 
243     /// <summary>
244     /// Predefined font weight : Ultra-black (950).
245     /// </summary>
246     DWRITE_FONT_WEIGHT_ULTRA_BLACK = 950
247 };
248 
249 /// <summary>
250 /// The font stretch enumeration describes relative change from the normal aspect ratio
251 /// as specified by a font designer for the glyphs in a font.
252 /// Values less than 1 or greater than 9 are considered to be invalid, and they are rejected by font API functions.
253 /// </summary>
254 enum DWRITE_FONT_STRETCH
255 {
256     /// <summary>
257     /// Predefined font stretch : Not known (0).
258     /// </summary>
259     DWRITE_FONT_STRETCH_UNDEFINED = 0,
260 
261     /// <summary>
262     /// Predefined font stretch : Ultra-condensed (1).
263     /// </summary>
264     DWRITE_FONT_STRETCH_ULTRA_CONDENSED = 1,
265 
266     /// <summary>
267     /// Predefined font stretch : Extra-condensed (2).
268     /// </summary>
269     DWRITE_FONT_STRETCH_EXTRA_CONDENSED = 2,
270 
271     /// <summary>
272     /// Predefined font stretch : Condensed (3).
273     /// </summary>
274     DWRITE_FONT_STRETCH_CONDENSED = 3,
275 
276     /// <summary>
277     /// Predefined font stretch : Semi-condensed (4).
278     /// </summary>
279     DWRITE_FONT_STRETCH_SEMI_CONDENSED = 4,
280 
281     /// <summary>
282     /// Predefined font stretch : Normal (5).
283     /// </summary>
284     DWRITE_FONT_STRETCH_NORMAL = 5,
285 
286     /// <summary>
287     /// Predefined font stretch : Medium (5).
288     /// </summary>
289     DWRITE_FONT_STRETCH_MEDIUM = 5,
290 
291     /// <summary>
292     /// Predefined font stretch : Semi-expanded (6).
293     /// </summary>
294     DWRITE_FONT_STRETCH_SEMI_EXPANDED = 6,
295 
296     /// <summary>
297     /// Predefined font stretch : Expanded (7).
298     /// </summary>
299     DWRITE_FONT_STRETCH_EXPANDED = 7,
300 
301     /// <summary>
302     /// Predefined font stretch : Extra-expanded (8).
303     /// </summary>
304     DWRITE_FONT_STRETCH_EXTRA_EXPANDED = 8,
305 
306     /// <summary>
307     /// Predefined font stretch : Ultra-expanded (9).
308     /// </summary>
309     DWRITE_FONT_STRETCH_ULTRA_EXPANDED = 9
310 };
311 
312 /// <summary>
313 /// The font style enumeration describes the slope style of a font face, such as Normal, Italic or Oblique.
314 /// Values other than the ones defined in the enumeration are considered to be invalid, and they are rejected by font API functions.
315 /// </summary>
316 enum DWRITE_FONT_STYLE
317 {
318     /// <summary>
319     /// Font slope style : Normal.
320     /// </summary>
321     DWRITE_FONT_STYLE_NORMAL,
322 
323     /// <summary>
324     /// Font slope style : Oblique.
325     /// </summary>
326     DWRITE_FONT_STYLE_OBLIQUE,
327 
328     /// <summary>
329     /// Font slope style : Italic.
330     /// </summary>
331     DWRITE_FONT_STYLE_ITALIC
332 
333 };
334 
335 /// <summary>
336 /// The informational string enumeration identifies a string in a font.
337 /// </summary>
338 enum DWRITE_INFORMATIONAL_STRING_ID
339 {
340     /// <summary>
341     /// Unspecified name ID.
342     /// </summary>
343     DWRITE_INFORMATIONAL_STRING_NONE,
344 
345     /// <summary>
346     /// Copyright notice provided by the font.
347     /// </summary>
348     DWRITE_INFORMATIONAL_STRING_COPYRIGHT_NOTICE,
349 
350     /// <summary>
351     /// String containing a version number.
352     /// </summary>
353     DWRITE_INFORMATIONAL_STRING_VERSION_STRINGS,
354 
355     /// <summary>
356     /// Trademark information provided by the font.
357     /// </summary>
358     DWRITE_INFORMATIONAL_STRING_TRADEMARK,
359 
360     /// <summary>
361     /// Name of the font manufacturer.
362     /// </summary>
363     DWRITE_INFORMATIONAL_STRING_MANUFACTURER,
364 
365     /// <summary>
366     /// Name of the font designer.
367     /// </summary>
368     DWRITE_INFORMATIONAL_STRING_DESIGNER,
369 
370     /// <summary>
371     /// URL of font designer (with protocol, e.g., http://, ftp://).
372     /// </summary>
373     DWRITE_INFORMATIONAL_STRING_DESIGNER_URL,
374 
375     /// <summary>
376     /// Description of the font. Can contain revision information, usage recommendations, history, features, etc.
377     /// </summary>
378     DWRITE_INFORMATIONAL_STRING_DESCRIPTION,
379 
380     /// <summary>
381     /// 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.
382     /// </summary>
383     DWRITE_INFORMATIONAL_STRING_FONT_VENDOR_URL,
384 
385     /// <summary>
386     /// 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.
387     /// </summary>
388     DWRITE_INFORMATIONAL_STRING_LICENSE_DESCRIPTION,
389 
390     /// <summary>
391     /// URL where additional licensing information can be found.
392     /// </summary>
393     DWRITE_INFORMATIONAL_STRING_LICENSE_INFO_URL,
394 
395     /// <summary>
396     /// 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
397     /// (e.g., "Arial", "Arial Narrow", "Arial Black").
398     /// </summary>
399     DWRITE_INFORMATIONAL_STRING_WIN32_FAMILY_NAMES,
400 
401     /// <summary>
402     /// GDI-compatible subfamily name.
403     /// </summary>
404     DWRITE_INFORMATIONAL_STRING_WIN32_SUBFAMILY_NAMES,
405 
406     /// <summary>
407     /// Family name preferred by the designer. This enables font designers to group more than four fonts in a single family without losing compatibility with
408     /// GDI. This name is typically only present if it differs from the GDI-compatible family name.
409     /// </summary>
410     DWRITE_INFORMATIONAL_STRING_PREFERRED_FAMILY_NAMES,
411 
412     /// <summary>
413     /// Subfamily name preferred by the designer. This name is typically only present if it differs from the GDI-compatible subfamily name.
414     /// </summary>
415     DWRITE_INFORMATIONAL_STRING_PREFERRED_SUBFAMILY_NAMES,
416 
417     /// <summary>
418     /// 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.
419     /// </summary>
420     DWRITE_INFORMATIONAL_STRING_SAMPLE_TEXT
421 };
422 
423 
424 /// <summary>
425 /// The DWRITE_FONT_METRICS structure specifies the metrics of a font face that
426 /// are applicable to all glyphs within the font face.
427 /// </summary>
428 struct DWRITE_FONT_METRICS
429 {
430     /// <summary>
431     /// The number of font design units per em unit.
432     /// Font files use their own coordinate system of font design units.
433     /// A font design unit is the smallest measurable unit in the em square,
434     /// an imaginary square that is used to size and align glyphs.
435     /// The concept of em square is used as a reference scale factor when defining font size and device transformation semantics.
436     /// The size of one em square is also commonly used to compute the paragraph identation value.
437     /// </summary>
438     UINT16 designUnitsPerEm;
439 
440     /// <summary>
441     /// Ascent value of the font face in font design units.
442     /// Ascent is the distance from the top of font character alignment box to English baseline.
443     /// </summary>
444     UINT16 ascent;
445 
446     /// <summary>
447     /// Descent value of the font face in font design units.
448     /// Descent is the distance from the bottom of font character alignment box to English baseline.
449     /// </summary>
450     UINT16 descent;
451 
452     /// <summary>
453     /// Line gap in font design units.
454     /// Recommended additional white space to add between lines to improve legibility. The recommended line spacing
455     /// (baseline-to-baseline distance) is thus the sum of ascent, descent, and lineGap. The line gap is usually
456     /// positive or zero but can be negative, in which case the recommended line spacing is less than the height
457     /// of the character alignment box.
458     /// </summary>
459     INT16 lineGap;
460 
461     /// <summary>
462     /// Cap height value of the font face in font design units.
463     /// Cap height is the distance from English baseline to the top of a typical English capital.
464     /// Capital "H" is often used as a reference character for the purpose of calculating the cap height value.
465     /// </summary>
466     UINT16 capHeight;
467 
468     /// <summary>
469     /// x-height value of the font face in font design units.
470     /// x-height is the distance from English baseline to the top of lowercase letter "x", or a similar lowercase character.
471     /// </summary>
472     UINT16 xHeight;
473 
474     /// <summary>
475     /// The underline position value of the font face in font design units.
476     /// Underline position is the position of underline relative to the English baseline.
477     /// The value is usually made negative in order to place the underline below the baseline.
478     /// </summary>
479     INT16 underlinePosition;
480 
481     /// <summary>
482     /// The suggested underline thickness value of the font face in font design units.
483     /// </summary>
484     UINT16 underlineThickness;
485 
486     /// <summary>
487     /// The strikethrough position value of the font face in font design units.
488     /// Strikethrough position is the position of strikethrough relative to the English baseline.
489     /// The value is usually made positive in order to place the strikethrough above the baseline.
490     /// </summary>
491     INT16 strikethroughPosition;
492 
493     /// <summary>
494     /// The suggested strikethrough thickness value of the font face in font design units.
495     /// </summary>
496     UINT16 strikethroughThickness;
497 };
498 
499 /// <summary>
500 /// The DWRITE_GLYPH_METRICS structure specifies the metrics of an individual glyph.
501 /// The units depend on how the metrics are obtained.
502 /// </summary>
503 struct DWRITE_GLYPH_METRICS
504 {
505     /// <summary>
506     /// Specifies the X offset from the glyph origin to the left edge of the black box.
507     /// The glyph origin is the current horizontal writing position.
508     /// A negative value means the black box extends to the left of the origin (often true for lowercase italic 'f').
509     /// </summary>
510     INT32 leftSideBearing;
511 
512     /// <summary>
513     /// Specifies the X offset from the origin of the current glyph to the origin of the next glyph when writing horizontally.
514     /// </summary>
515     UINT32 advanceWidth;
516 
517     /// <summary>
518     /// Specifies the X offset from the right edge of the black box to the origin of the next glyph when writing horizontally.
519     /// The value is negative when the right edge of the black box overhangs the layout box.
520     /// </summary>
521     INT32 rightSideBearing;
522 
523     /// <summary>
524     /// Specifies the vertical offset from the vertical origin to the top of the black box.
525     /// Thus, a positive value adds whitespace whereas a negative value means the glyph overhangs the top of the layout box.
526     /// </summary>
527     INT32 topSideBearing;
528 
529     /// <summary>
530     /// Specifies the Y offset from the vertical origin of the current glyph to the vertical origin of the next glyph when writing vertically.
531     /// (Note that the term "origin" by itself denotes the horizontal origin. The vertical origin is different.
532     /// Its Y coordinate is specified by verticalOriginY value,
533     /// and its X coordinate is half the advanceWidth to the right of the horizontal origin).
534     /// </summary>
535     UINT32 advanceHeight;
536 
537     /// <summary>
538     /// Specifies the vertical distance from the black box's bottom edge to the advance height.
539     /// Positive when the bottom edge of the black box is within the layout box.
540     /// Negative when the bottom edge of black box overhangs the layout box.
541     /// </summary>
542     INT32 bottomSideBearing;
543 
544     /// <summary>
545     /// Specifies the Y coordinate of a glyph's vertical origin, in the font's design coordinate system.
546     /// The y coordinate of a glyph's vertical origin is the sum of the glyph's top side bearing
547     /// and the top (i.e. yMax) of the glyph's bounding box.
548     /// </summary>
549     INT32 verticalOriginY;
550 };
551 
552 /// <summary>
553 /// Optional adjustment to a glyph's position. An glyph offset changes the position of a glyph without affecting
554 /// the pen position. Offsets are in logical, pre-transform units.
555 /// </summary>
556 struct DWRITE_GLYPH_OFFSET
557 {
558     /// <summary>
559     /// Offset in the advance direction of the run. A positive advance offset moves the glyph to the right
560     /// (in pre-transform coordinates) if the run is left-to-right or to the left if the run is right-to-left.
561     /// </summary>
562     FLOAT advanceOffset;
563 
564     /// <summary>
565     /// Offset in the ascent direction, i.e., the direction ascenders point. A positive ascender offset moves
566     /// the glyph up (in pre-transform coordinates).
567     /// </summary>
568     FLOAT ascenderOffset;
569 };
570 
571 /// <summary>
572 /// Specifies the type of DirectWrite factory object.
573 /// DirectWrite factory contains internal state such as font loader registration and cached font data.
574 /// In most cases it is recommended to use the shared factory object, because it allows multiple components
575 /// that use DirectWrite to share internal DirectWrite state and reduce memory usage.
576 /// However, there are cases when it is desirable to reduce the impact of a component,
577 /// such as a plug-in from an untrusted source, on the rest of the process by sandboxing and isolating it
578 /// from the rest of the process components. In such cases, it is recommended to use an isolated factory for the sandboxed
579 /// component.
580 /// </summary>
581 enum DWRITE_FACTORY_TYPE
582 {
583     /// <summary>
584     /// Shared factory allow for re-use of cached font data across multiple in process components.
585     /// Such factories also take advantage of cross process font caching components for better performance.
586     /// </summary>
587     DWRITE_FACTORY_TYPE_SHARED,
588 
589     /// <summary>
590     /// Objects created from the isolated factory do not interact with internal DirectWrite state from other components.
591     /// </summary>
592     DWRITE_FACTORY_TYPE_ISOLATED
593 };
594 
595 // Creates an OpenType tag as a 32bit integer such that
596 // the first character in the tag is the lowest byte,
597 // (least significant on little endian architectures)
598 // which can be used to compare with tags in the font file.
599 // This macro is compatible with DWRITE_FONT_FEATURE_TAG.
600 //
601 // Example: DWRITE_MAKE_OPENTYPE_TAG('c','c','m','p')
602 // Dword:   0x706D6363
603 //
604 #define DWRITE_MAKE_OPENTYPE_TAG(a,b,c,d) ( \
605     (static_cast<UINT32>(static_cast<UINT8>(d)) << 24) | \
606     (static_cast<UINT32>(static_cast<UINT8>(c)) << 16) | \
607     (static_cast<UINT32>(static_cast<UINT8>(b)) << 8)  | \
608      static_cast<UINT32>(static_cast<UINT8>(a)))
609 
610 interface IDWriteFontFileStream;
611 
612 /// <summary>
613 /// Font file loader interface handles loading font file resources of a particular type from a key.
614 /// The font file loader interface is recommended to be implemented by a singleton object.
615 /// IMPORTANT: font file loader implementations must not register themselves with DirectWrite factory
616 /// inside their constructors and must not unregister themselves in their destructors, because
617 /// registration and unregistraton operations increment and decrement the object reference count respectively.
618 /// Instead, registration and unregistration of font file loaders with DirectWrite factory should be performed
619 /// outside of the font file loader implementation as a separate step.
620 /// </summary>
621 interface DWRITE_DECLARE_INTERFACE("727cad4e-d6af-4c9e-8a08-d695b11caa49") IDWriteFontFileLoader : public IUnknown
622 {
623     /// <summary>
624     /// Creates a font file stream object that encapsulates an open file resource.
625     /// The resource is closed when the last reference to fontFileStream is released.
626     /// </summary>
627     /// <param name="fontFileReferenceKey">Font file reference key that uniquely identifies the font file resource
628     /// within the scope of the font loader being used.</param>
629     /// <param name="fontFileReferenceKeySize">Size of font file reference key in bytes.</param>
630     /// <param name="fontFileStream">Pointer to the newly created font file stream.</param>
631     /// <returns>
632     /// Standard HRESULT error code.
633     /// </returns>
634     STDMETHOD(CreateStreamFromKey)(
635         __in_bcount(fontFileReferenceKeySize) void const* fontFileReferenceKey,
636         UINT32 fontFileReferenceKeySize,
637         __out IDWriteFontFileStream** fontFileStream
638         ) PURE;
639 };
640 
641 /// <summary>
642 /// A built-in implementation of IDWriteFontFileLoader interface that operates on local font files
643 /// and exposes local font file information from the font file reference key.
644 /// Font file references created using CreateFontFileReference use this font file loader.
645 /// </summary>
646 interface DWRITE_DECLARE_INTERFACE("b2d9f3ec-c9fe-4a11-a2ec-d86208f7c0a2") IDWriteLocalFontFileLoader : public IDWriteFontFileLoader
647 {
648     /// <summary>
649     /// Obtains the length of the absolute file path from the font file reference key.
650     /// </summary>
651     /// <param name="fontFileReferenceKey">Font file reference key that uniquely identifies the local font file
652     /// within the scope of the font loader being used.</param>
653     /// <param name="fontFileReferenceKeySize">Size of font file reference key in bytes.</param>
654     /// <param name="filePathLength">Length of the file path string not including the terminated NULL character.</param>
655     /// <returns>
656     /// Standard HRESULT error code.
657     /// </returns>
658     STDMETHOD(GetFilePathLengthFromKey)(
659         __in_bcount(fontFileReferenceKeySize) void const* fontFileReferenceKey,
660         UINT32 fontFileReferenceKeySize,
661         __out UINT32* filePathLength
662         ) PURE;
663 
664     /// <summary>
665     /// Obtains the absolute font file path from the font file reference key.
666     /// </summary>
667     /// <param name="fontFileReferenceKey">Font file reference key that uniquely identifies the local font file
668     /// within the scope of the font loader being used.</param>
669     /// <param name="fontFileReferenceKeySize">Size of font file reference key in bytes.</param>
670     /// <param name="filePath">Character array that receives the local file path.</param>
671     /// <param name="filePathSize">Size of the filePath array in character count including the terminated NULL character.</param>
672     /// <returns>
673     /// Standard HRESULT error code.
674     /// </returns>
675     STDMETHOD(GetFilePathFromKey)(
676         __in_bcount(fontFileReferenceKeySize) void const* fontFileReferenceKey,
677         UINT32 fontFileReferenceKeySize,
678         __out_ecount_z(filePathSize) WCHAR* filePath,
679         UINT32 filePathSize
680         ) PURE;
681 
682     /// <summary>
683     /// Obtains the last write time of the file from the font file reference key.
684     /// </summary>
685     /// <param name="fontFileReferenceKey">Font file reference key that uniquely identifies the local font file
686     /// within the scope of the font loader being used.</param>
687     /// <param name="fontFileReferenceKeySize">Size of font file reference key in bytes.</param>
688     /// <param name="lastWriteTime">Last modified time of the font file.</param>
689     /// <returns>
690     /// Standard HRESULT error code.
691     /// </returns>
692     STDMETHOD(GetLastWriteTimeFromKey)(
693         __in_bcount(fontFileReferenceKeySize) void const* fontFileReferenceKey,
694         UINT32 fontFileReferenceKeySize,
695         __out FILETIME* lastWriteTime
696         ) PURE;
697 };
698 
699 /// <summary>
700 /// The interface for loading font file data.
701 /// </summary>
702 interface DWRITE_DECLARE_INTERFACE("6d4865fe-0ab8-4d91-8f62-5dd6be34a3e0") IDWriteFontFileStream : public IUnknown
703 {
704     /// <summary>
705     /// Reads a fragment from a file.
706     /// </summary>
707     /// <param name="fragmentStart">Receives the pointer to the start of the font file fragment.</param>
708     /// <param name="fileOffset">Offset of the fragment from the beginning of the font file.</param>
709     /// <param name="fragmentSize">Size of the fragment in bytes.</param>
710     /// <param name="fragmentContext">The client defined context to be passed to the ReleaseFileFragment.</param>
711     /// <returns>
712     /// Standard HRESULT error code.
713     /// </returns>
714     /// <remarks>
715     /// IMPORTANT: ReadFileFragment() implementations must check whether the requested file fragment
716     /// is within the file bounds. Otherwise, an error should be returned from ReadFileFragment.
717     /// </remarks>
718     STDMETHOD(ReadFileFragment)(
719         __deref_out_bcount(fragmentSize) void const** fragmentStart,
720         UINT64 fileOffset,
721         UINT64 fragmentSize,
722         __out void** fragmentContext
723         ) PURE;
724 
725     /// <summary>
726     /// Releases a fragment from a file.
727     /// </summary>
728     /// <param name="fragmentContext">The client defined context of a font fragment returned from ReadFileFragment.</param>
729     STDMETHOD_(void, ReleaseFileFragment)(
730         void* fragmentContext
731         ) PURE;
732 
733     /// <summary>
734     /// Obtains the total size of a file.
735     /// </summary>
736     /// <param name="fileSize">Receives the total size of the file.</param>
737     /// <returns>
738     /// Standard HRESULT error code.
739     /// </returns>
740     /// <remarks>
741     /// Implementing GetFileSize() for asynchronously loaded font files may require
742     /// downloading the complete file contents, therefore this method should only be used for operations that
743     /// either require complete font file to be loaded (e.g., copying a font file) or need to make
744     /// decisions based on the value of the file size (e.g., validation against a persisted file size).
745     /// </remarks>
746     STDMETHOD(GetFileSize)(
747         __out UINT64* fileSize
748         ) PURE;
749 
750     /// <summary>
751     /// Obtains the last modified time of the file. The last modified time is used by DirectWrite font selection algorithms
752     /// to determine whether one font resource is more up to date than another one.
753     /// </summary>
754     /// <param name="lastWriteTime">Receives the last modifed time of the file in the format that represents
755     /// the number of 100-nanosecond intervals since January 1, 1601 (UTC).</param>
756     /// <returns>
757     /// Standard HRESULT error code. For resources that don't have a concept of the last modified time, the implementation of
758     /// GetLastWriteTime should return E_NOTIMPL.
759     /// </returns>
760     STDMETHOD(GetLastWriteTime)(
761         __out UINT64* lastWriteTime
762         ) PURE;
763 };
764 
765 /// <summary>
766 /// The interface that represents a reference to a font file.
767 /// </summary>
768 interface DWRITE_DECLARE_INTERFACE("739d886a-cef5-47dc-8769-1a8b41bebbb0") IDWriteFontFile : public IUnknown
769 {
770     /// <summary>
771     /// 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.
772     /// </summary>
773     /// <param name="fontFileReferenceKey">Pointer to the font file reference key.
774     /// IMPORTANT: The pointer value is valid until the font file reference object it is obtained from is released.</param>
775     /// <param name="fontFileReferenceKeySize">Size of font file reference key in bytes.</param>
776     /// <returns>
777     /// Standard HRESULT error code.
778     /// </returns>
779     STDMETHOD(GetReferenceKey)(
780         __deref_out_bcount(*fontFileReferenceKeySize) void const** fontFileReferenceKey,
781         __out UINT32* fontFileReferenceKeySize
782         ) PURE;
783 
784     /// <summary>
785     /// Obtains the file loader associated with a font file object.
786     /// </summary>
787     /// <param name="fontFileLoader">The font file loader associated with the font file object.</param>
788     /// <returns>
789     /// Standard HRESULT error code.
790     /// </returns>
791     STDMETHOD(GetLoader)(
792         __out IDWriteFontFileLoader** fontFileLoader
793         ) PURE;
794 
795     /// <summary>
796     /// Analyzes a file and returns whether it represents a font, and whether the font type is supported by the font system.
797     /// </summary>
798     /// <param name="isSupportedFontType">TRUE if the font type is supported by the font system, FALSE otherwise.</param>
799     /// <param name="fontFileType">The type of the font file. Note that even if isSupportedFontType is FALSE,
800     /// the fontFileType value may be different from DWRITE_FONT_FILE_TYPE_UNKNOWN.</param>
801     /// <param name="fontFaceType">The type of the font face that can be constructed from the font file.
802     /// Note that even if isSupportedFontType is FALSE, the fontFaceType value may be different from
803     /// DWRITE_FONT_FACE_TYPE_UNKNOWN.</param>
804     /// <param name="numberOfFaces">Number of font faces contained in the font file.</param>
805     /// <returns>
806     /// Standard HRESULT error code if there was a processing error during analysis.
807     /// </returns>
808     /// <remarks>
809     /// IMPORTANT: certain font file types are recognized, but not supported by the font system.
810     /// For example, the font system will recognize a file as a Type 1 font file,
811     /// but will not be able to construct a font face object from it. In such situations, Analyze will set
812     /// isSupportedFontType output parameter to FALSE.
813     /// </remarks>
814     STDMETHOD(Analyze)(
815         __out BOOL* isSupportedFontType,
816         __out DWRITE_FONT_FILE_TYPE* fontFileType,
817         __out_opt DWRITE_FONT_FACE_TYPE* fontFaceType,
818         __out UINT32* numberOfFaces
819         ) PURE;
820 };
821 
822 /// <summary>
823 /// Represents the internal structure of a device pixel (i.e., the physical arrangement of red,
824 /// green, and blue color components) that is assumed for purposes of rendering text.
825 /// </summary>
826 #ifndef DWRITE_PIXEL_GEOMETRY_DEFINED
827 enum DWRITE_PIXEL_GEOMETRY
828 {
829     /// <summary>
830     /// The red, green, and blue color components of each pixel are assumed to occupy the same point.
831     /// </summary>
832     DWRITE_PIXEL_GEOMETRY_FLAT,
833 
834     /// <summary>
835     /// Each pixel comprises three vertical stripes, with red on the left, green in the center, and
836     /// blue on the right. This is the most common pixel geometry for LCD monitors.
837     /// </summary>
838     DWRITE_PIXEL_GEOMETRY_RGB,
839 
840     /// <summary>
841     /// Each pixel comprises three vertical stripes, with blue on the left, green in the center, and
842     /// red on the right.
843     /// </summary>
844     DWRITE_PIXEL_GEOMETRY_BGR
845 };
846 #define DWRITE_PIXEL_GEOMETRY_DEFINED
847 #endif
848 
849 /// <summary>
850 /// Represents a method of rendering glyphs.
851 /// </summary>
852 enum DWRITE_RENDERING_MODE
853 {
854     /// <summary>
855     /// Specifies that the rendering mode is determined automatically based on the font and size.
856     /// </summary>
857     DWRITE_RENDERING_MODE_DEFAULT,
858 
859     /// <summary>
860     /// Specifies that no anti-aliasing is performed. Each pixel is either set to the foreground
861     /// color of the text or retains the color of the background.
862     /// </summary>
863     DWRITE_RENDERING_MODE_ALIASED,
864 
865     /// <summary>
866     /// Specifies ClearType rendering with the same metrics as aliased text. Glyphs can only
867     /// be positioned on whole-pixel boundaries.
868     /// </summary>
869     DWRITE_RENDERING_MODE_CLEARTYPE_GDI_CLASSIC,
870 
871     /// <summary>
872     /// Specifies ClearType rendering with the same metrics as text rendering using GDI using a font
873     /// created with CLEARTYPE_NATURAL_QUALITY. Glyph metrics are closer to their ideal values than
874     /// with aliased text, but glyphs are still positioned on whole-pixel boundaries.
875     /// </summary>
876     DWRITE_RENDERING_MODE_CLEARTYPE_GDI_NATURAL,
877 
878     /// <summary>
879     /// Specifies ClearType rendering with anti-aliasing in the horizontal dimension only. This is
880     /// typically used with small to medium font sizes (up to 16 ppem).
881     /// </summary>
882     DWRITE_RENDERING_MODE_CLEARTYPE_NATURAL,
883 
884     /// <summary>
885     /// Specifies ClearType rendering with anti-aliasing in both horizontal and vertical dimensions.
886     /// This is typically used at larger sizes to makes curves and diagonal lines look smoother, at
887     /// the expense of some softness.
888     /// </summary>
889     DWRITE_RENDERING_MODE_CLEARTYPE_NATURAL_SYMMETRIC,
890 
891     /// <summary>
892     /// Specifies that rendering should bypass the rasterizer and use the outlines directly. This is
893     /// typically used at very large sizes.
894     /// </summary>
895     DWRITE_RENDERING_MODE_OUTLINE
896 };
897 
898 /// <summary>
899 /// The DWRITE_MATRIX structure specifies the graphics transform to be applied
900 /// to rendered glyphs.
901 /// </summary>
902 struct DWRITE_MATRIX
903 {
904     /// <summary>
905     /// Horizontal scaling / cosine of rotation
906     /// </summary>
907     FLOAT m11;
908 
909     /// <summary>
910     /// Vertical shear / sine of rotation
911     /// </summary>
912     FLOAT m12;
913 
914     /// <summary>
915     /// Horizontal shear / negative sine of rotation
916     /// </summary>
917     FLOAT m21;
918 
919     /// <summary>
920     /// Vertical scaling / cosine of rotation
921     /// </summary>
922     FLOAT m22;
923 
924     /// <summary>
925     /// Horizontal shift (always orthogonal regardless of rotation)
926     /// </summary>
927     FLOAT dx;
928 
929     /// <summary>
930     /// Vertical shift (always orthogonal regardless of rotation)
931     /// </summary>
932     FLOAT dy;
933 };
934 
935 /// <summary>
936 /// The interface that represents text rendering settings for glyph rasterization and filtering.
937 /// </summary>
938 interface DWRITE_DECLARE_INTERFACE("2f0da53a-2add-47cd-82ee-d9ec34688e75") IDWriteRenderingParams : public IUnknown
939 {
940     /// <summary>
941     /// Gets the gamma value used for gamma correction. Valid values must be
942     /// greater than zero and cannot exceed 256.
943     /// </summary>
944     STDMETHOD_(FLOAT, GetGamma)() PURE;
945 
946     /// <summary>
947     /// Gets the amount of contrast enhancement. Valid values are greater than
948     /// or equal to zero.
949     /// </summary>
950     STDMETHOD_(FLOAT, GetEnhancedContrast)() PURE;
951 
952     /// <summary>
953     /// Gets the ClearType level. Valid values range from 0.0f (no ClearType)
954     /// to 1.0f (full ClearType).
955     /// </summary>
956     STDMETHOD_(FLOAT, GetClearTypeLevel)() PURE;
957 
958     /// <summary>
959     /// Gets the pixel geometry.
960     /// </summary>
961     STDMETHOD_(DWRITE_PIXEL_GEOMETRY, GetPixelGeometry)() PURE;
962 
963     /// <summary>
964     /// Gets the rendering mode.
965     /// </summary>
966     STDMETHOD_(DWRITE_RENDERING_MODE, GetRenderingMode)() PURE;
967 };
968 
969 // Forward declarations of D2D types
970 interface ID2D1SimplifiedGeometrySink;
971 
972 typedef ID2D1SimplifiedGeometrySink IDWriteGeometrySink;
973 
974 /// <summary>
975 /// The interface that represents an absolute reference to a font face.
976 /// It contains font face type, appropriate file references and face identification data.
977 /// Various font data such as metrics, names and glyph outlines is obtained from IDWriteFontFace.
978 /// </summary>
979 interface DWRITE_DECLARE_INTERFACE("5f49804d-7024-4d43-bfa9-d25984f53849") IDWriteFontFace : public IUnknown
980 {
981     /// <summary>
982     /// Obtains the file format type of a font face.
983     /// </summary>
984     STDMETHOD_(DWRITE_FONT_FACE_TYPE, GetType)() PURE;
985 
986     /// <summary>
987     /// Obtains the font files representing a font face.
988     /// </summary>
989     /// <param name="numberOfFiles">The number of files representing the font face.</param>
990     /// <param name="fontFiles">User provided array that stores pointers to font files representing the font face.
991     /// This parameter can be NULL if the user is only interested in the number of files representing the font face.
992     /// This API increments reference count of the font file pointers returned according to COM conventions, and the client
993     /// should release them when finished.</param>
994     /// <returns>
995     /// Standard HRESULT error code.
996     /// </returns>
997     STDMETHOD(GetFiles)(
998         __inout UINT32* numberOfFiles,
999         __out_ecount_opt(*numberOfFiles) IDWriteFontFile** fontFiles
1000         ) PURE;
1001 
1002     /// <summary>
1003     /// Obtains the zero-based index of the font face in its font file or files. If the font files contain a single face,
1004     /// the return value is zero.
1005     /// </summary>
1006     STDMETHOD_(UINT32, GetIndex)() PURE;
1007 
1008     /// <summary>
1009     /// Obtains the algorithmic style simulation flags of a font face.
1010     /// </summary>
1011     STDMETHOD_(DWRITE_FONT_SIMULATIONS, GetSimulations)() PURE;
1012 
1013     /// <summary>
1014     /// Determines whether the font is a symbol font.
1015     /// </summary>
1016     STDMETHOD_(BOOL, IsSymbolFont)() PURE;
1017 
1018     /// <summary>
1019     /// Obtains design units and common metrics for the font face.
1020     /// These metrics are applicable to all the glyphs within a fontface and are used by applications for layout calculations.
1021     /// </summary>
1022     /// <param name="fontFaceMetrics">Points to a DWRITE_FONT_METRICS structure to fill in.
1023     /// The metrics returned by this function are in font design units.</param>
1024     STDMETHOD_(void, GetMetrics)(
1025         __out DWRITE_FONT_METRICS* fontFaceMetrics
1026         ) PURE;
1027 
1028     /// <summary>
1029     /// Obtains the number of glyphs in the font face.
1030     /// </summary>
1031     STDMETHOD_(UINT16, GetGlyphCount)() PURE;
1032 
1033     /// <summary>
1034     /// Obtains ideal glyph metrics in font design units. Design glyphs metrics are used for glyph positioning.
1035     /// </summary>
1036     /// <param name="glyphIndices">An array of glyph indices to compute the metrics for.</param>
1037     /// <param name="glyphCount">The number of elements in the glyphIndices array.</param>
1038     /// <param name="glyphMetrics">Array of DWRITE_GLYPH_METRICS structures filled by this function.
1039     /// The metrics returned by this function are in font design units.</param>
1040     /// <param name="isSideways">Indicates whether the font is being used in a sideways run.
1041     /// This can affect the glyph metrics if the font has oblique simulation
1042     /// because sideways oblique simulation differs from non-sideways oblique simulation.</param>
1043     /// <returns>
1044     /// Standard HRESULT error code. If any of the input glyph indices are outside of the valid glyph index range
1045     /// for the current font face, E_INVALIDARG will be returned.
1046     /// </returns>
1047     STDMETHOD(GetDesignGlyphMetrics)(
1048         __in_ecount(glyphCount) UINT16 const* glyphIndices,
1049         UINT32 glyphCount,
1050         __out_ecount(glyphCount) DWRITE_GLYPH_METRICS* glyphMetrics,
1051         BOOL isSideways = FALSE
1052         ) PURE;
1053 
1054     /// <summary>
1055     /// Returns the nominal mapping of UCS4 Unicode code points to glyph indices as defined by the font 'CMAP' table.
1056     /// Note that this mapping is primarily provided for line layout engines built on top of the physical font API.
1057     /// Because of OpenType glyph substitution and line layout character substitution, the nominal conversion does not always correspond
1058     /// to how a Unicode string will map to glyph indices when rendering using a particular font face.
1059     /// Also, note that Unicode Variant Selectors provide for alternate mappings for character to glyph.
1060     /// This call will always return the default variant.
1061     /// </summary>
1062     /// <param name="codePoints">An array of USC4 code points to obtain nominal glyph indices from.</param>
1063     /// <param name="codePointCount">The number of elements in the codePoints array.</param>
1064     /// <param name="glyphIndices">Array of nominal glyph indices filled by this function.</param>
1065     /// <returns>
1066     /// Standard HRESULT error code.
1067     /// </returns>
1068     STDMETHOD(GetGlyphIndices)(
1069         __in_ecount(codePointCount) UINT32 const* codePoints,
1070         UINT32 codePointCount,
1071         __out_ecount(codePointCount) UINT16* glyphIndices
1072         ) PURE;
1073 
1074     /// <summary>
1075     /// Finds the specified OpenType font table if it exists and returns a pointer to it.
1076     /// The function accesses the underling font data via the IDWriteFontStream interface
1077     /// implemented by the font file loader.
1078     /// </summary>
1079     /// <param name="openTypeTableTag">Four character tag of table to find.
1080     ///     Use the DWRITE_MAKE_OPENTYPE_TAG() macro to create it.
1081     ///     Unlike GDI, it does not support the special TTCF and null tags to access the whole font.</param>
1082     /// <param name="tableData">
1083     ///     Pointer to base of table in memory.
1084     ///     The pointer is only valid so long as the FontFace used to get the font table still exists
1085     ///     (not any other FontFace, even if it actually refers to the same physical font).
1086     /// </param>
1087     /// <param name="tableSize">Byte size of table.</param>
1088     /// <param name="tableContext">
1089     ///     Opaque context which must be freed by calling ReleaseFontTable.
1090     ///     The context actually comes from the lower level IDWriteFontFileStream,
1091     ///     which may be implemented by the application or DWrite itself.
1092     ///     It is possible for a NULL tableContext to be returned, especially if
1093     ///     the implementation directly memory maps the whole file.
1094     ///     Nevertheless, always release it later, and do not use it as a test for function success.
1095     ///     The same table can be queried multiple times,
1096     ///     but each returned context can be different, so release each separately.
1097     /// </param>
1098     /// <param name="exists">True if table exists.</param>
1099     /// <returns>
1100     /// Standard HRESULT error code.
1101     /// 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.
1102     /// The context does not need to be freed if the table was not found.
1103     /// </returns>
1104     /// <remarks>
1105     /// The context for the same tag may be different for each call,
1106     /// so each one must be held and released separately.
1107     /// </remarks>
1108     STDMETHOD(TryGetFontTable)(
1109         __in UINT32 openTypeTableTag,
1110         __deref_out_bcount(*tableSize) const void** tableData,
1111         __out UINT32* tableSize,
1112         __out void** tableContext,
1113         __out BOOL* exists
1114         ) PURE;
1115 
1116     /// <summary>
1117     /// Releases the table obtained earlier from TryGetFontTable.
1118     /// </summary>
1119     /// <param name="tableContext">Opaque context from TryGetFontTable.</param>
1120     /// <returns>
1121     /// Standard HRESULT error code.
1122     /// </returns>
1123     STDMETHOD_(void, ReleaseFontTable)(
1124         __in void* tableContext
1125         ) PURE;
1126 
1127     /// <summary>
1128     /// Computes the outline of a run of glyphs by calling back to the outline sink interface.
1129     /// </summary>
1130     /// <param name="emSize">Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.</param>
1131     /// <param name="glyphIndices">Array of glyph indices.</param>
1132     /// <param name="glyphAdvances">Optional array of glyph advances in DIPs.</param>
1133     /// <param name="glyphOffsets">Optional array of glyph offsets.</param>
1134     /// <param name="glyphCount">Number of glyphs.</param>
1135     /// <param name="isSideways">If true, specifies that glyphs are rotated 90 degrees to the left and vertical metrics are used.
1136     /// A client can render a vertical run by specifying isSideways = true and rotating the resulting geometry 90 degrees to the
1137     /// right using a transform. The isSideways and isRightToLeft parameters cannot both be true.</param>
1138     /// <param name="isRightToLeft">If true, specifies that the advance direction is right to left. By default, the advance direction
1139     /// is left to right.</param>
1140     /// <param name="geometrySink">Interface the function calls back to draw each element of the geometry.</param>
1141     /// <returns>
1142     /// Standard HRESULT error code.
1143     /// </returns>
1144     STDMETHOD(GetGlyphRunOutline)(
1145         FLOAT emSize,
1146         __in_ecount(glyphCount) UINT16 const* glyphIndices,
1147         __in_ecount_opt(glyphCount) FLOAT const* glyphAdvances,
1148         __in_ecount_opt(glyphCount) DWRITE_GLYPH_OFFSET const* glyphOffsets,
1149         UINT32 glyphCount,
1150         BOOL isSideways,
1151         BOOL isRightToLeft,
1152         IDWriteGeometrySink* geometrySink
1153         ) PURE;
1154 
1155     /// <summary>
1156     /// Determines the recommended rendering mode for the font given the specified size and rendering parameters.
1157     /// </summary>
1158     /// <param name="emSize">Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.</param>
1159     /// <param name="pixelsPerDip">Number of physical pixels per DIP. For example, if the DPI of the rendering surface is 96 this
1160     /// value is 1.0f. If the DPI is 120, this value is 120.0f/96.</param>
1161     /// <param name="measuringMode">Specifies measuring method that will be used for glyphs in the font.
1162     /// Renderer implementations may choose different rendering modes for given measuring methods, but
1163     /// best results are seen when the corresponding modes match:
1164     /// DWRITE_RENDERING_MODE_CLEARTYPE_NATURAL for DWRITE_MEASURING_MODE_NATURAL
1165     /// DWRITE_RENDERING_MODE_CLEARTYPE_GDI_CLASSIC for DWRITE_MEASURING_MODE_GDI_CLASSIC
1166     /// DWRITE_RENDERING_MODE_CLEARTYPE_GDI_NATURAL for DWRITE_MEASURING_MODE_GDI_NATURAL
1167     /// </param>
1168     /// <param name="renderingParams">Rendering parameters object. This parameter is necessary in case the rendering parameters
1169     /// object overrides the rendering mode.</param>
1170     /// <param name="renderingMode">Receives the recommended rendering mode to use.</param>
1171     /// <returns>
1172     /// Standard HRESULT error code.
1173     /// </returns>
1174     STDMETHOD(GetRecommendedRenderingMode)(
1175         FLOAT emSize,
1176         FLOAT pixelsPerDip,
1177         DWRITE_MEASURING_MODE measuringMode,
1178         IDWriteRenderingParams* renderingParams,
1179         __out DWRITE_RENDERING_MODE* renderingMode
1180         ) PURE;
1181 
1182     /// <summary>
1183     /// Obtains design units and common metrics for the font face.
1184     /// These metrics are applicable to all the glyphs within a fontface and are used by applications for layout calculations.
1185     /// </summary>
1186     /// <param name="emSize">Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.</param>
1187     /// <param name="pixelsPerDip">Number of physical pixels per DIP. For example, if the DPI of the rendering surface is 96 this
1188     /// value is 1.0f. If the DPI is 120, this value is 120.0f/96.</param>
1189     /// <param name="transform">Optional transform applied to the glyphs and their positions. This transform is applied after the
1190     /// scaling specified by the font size and pixelsPerDip.</param>
1191     /// <param name="fontFaceMetrics">Points to a DWRITE_FONT_METRICS structure to fill in.
1192     /// The metrics returned by this function are in font design units.</param>
1193     STDMETHOD(GetGdiCompatibleMetrics)(
1194         FLOAT emSize,
1195         FLOAT pixelsPerDip,
1196         __in_opt DWRITE_MATRIX const* transform,
1197         __out DWRITE_FONT_METRICS* fontFaceMetrics
1198         ) PURE;
1199 
1200 
1201     /// <summary>
1202     /// Obtains glyph metrics in font design units with the return values compatible with what GDI would produce.
1203     /// Glyphs metrics are used for positioning of individual glyphs.
1204     /// </summary>
1205     /// <param name="emSize">Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.</param>
1206     /// <param name="pixelsPerDip">Number of physical pixels per DIP. For example, if the DPI of the rendering surface is 96 this
1207     /// value is 1.0f. If the DPI is 120, this value is 120.0f/96.</param>
1208     /// <param name="transform">Optional transform applied to the glyphs and their positions. This transform is applied after the
1209     /// scaling specified by the font size and pixelsPerDip.</param>
1210     /// <param name="useGdiNatural">
1211     /// When set to FALSE, the metrics are the same as the metrics of GDI aliased text.
1212     /// When set to TRUE, the metrics are the same as the metrics of text measured by GDI using a font
1213     /// created with CLEARTYPE_NATURAL_QUALITY.
1214     /// </param>
1215     /// <param name="glyphIndices">An array of glyph indices to compute the metrics for.</param>
1216     /// <param name="glyphCount">The number of elements in the glyphIndices array.</param>
1217     /// <param name="glyphMetrics">Array of DWRITE_GLYPH_METRICS structures filled by this function.
1218     /// The metrics returned by this function are in font design units.</param>
1219     /// <param name="isSideways">Indicates whether the font is being used in a sideways run.
1220     /// This can affect the glyph metrics if the font has oblique simulation
1221     /// because sideways oblique simulation differs from non-sideways oblique simulation.</param>
1222     /// <returns>
1223     /// Standard HRESULT error code. If any of the input glyph indices are outside of the valid glyph index range
1224     /// for the current font face, E_INVALIDARG will be returned.
1225     /// </returns>
1226     STDMETHOD(GetGdiCompatibleGlyphMetrics)(
1227         FLOAT emSize,
1228         FLOAT pixelsPerDip,
1229         __in_opt DWRITE_MATRIX const* transform,
1230         BOOL useGdiNatural,
1231         __in_ecount(glyphCount) UINT16 const* glyphIndices,
1232         UINT32 glyphCount,
1233         __out_ecount(glyphCount) DWRITE_GLYPH_METRICS* glyphMetrics,
1234         BOOL isSideways = FALSE
1235         ) PURE;
1236 };
1237 
1238 interface IDWriteFactory;
1239 interface IDWriteFontFileEnumerator;
1240 
1241 /// <summary>
1242 /// The font collection loader interface is used to construct a collection of fonts given a particular type of key.
1243 /// The font collection loader interface is recommended to be implemented by a singleton object.
1244 /// IMPORTANT: font collection loader implementations must not register themselves with a DirectWrite factory
1245 /// inside their constructors and must not unregister themselves in their destructors, because
1246 /// registration and unregistraton operations increment and decrement the object reference count respectively.
1247 /// Instead, registration and unregistration of font file loaders with DirectWrite factory should be performed
1248 /// outside of the font file loader implementation as a separate step.
1249 /// </summary>
1250 interface DWRITE_DECLARE_INTERFACE("cca920e4-52f0-492b-bfa8-29c72ee0a468") IDWriteFontCollectionLoader : public IUnknown
1251 {
1252     /// <summary>
1253     /// Creates a font file enumerator object that encapsulates a collection of font files.
1254     /// The font system calls back to this interface to create a font collection.
1255     /// </summary>
1256     /// <param name="factory">Factory associated with the loader.</param>
1257     /// <param name="collectionKey">Font collection key that uniquely identifies the collection of font files within
1258     /// the scope of the font collection loader being used.</param>
1259     /// <param name="collectionKeySize">Size of the font collection key in bytes.</param>
1260     /// <param name="fontFileEnumerator">Pointer to the newly created font file enumerator.</param>
1261     /// <returns>
1262     /// Standard HRESULT error code.
1263     /// </returns>
1264     STDMETHOD(CreateEnumeratorFromKey)(
1265         IDWriteFactory* factory,
1266         __in_bcount(collectionKeySize) void const* collectionKey,
1267         UINT32 collectionKeySize,
1268         __out IDWriteFontFileEnumerator** fontFileEnumerator
1269         ) PURE;
1270 };
1271 
1272 /// <summary>
1273 /// The font file enumerator interface encapsulates a collection of font files. The font system uses this interface
1274 /// to enumerate font files when building a font collection.
1275 /// </summary>
1276 interface DWRITE_DECLARE_INTERFACE("72755049-5ff7-435d-8348-4be97cfa6c7c") IDWriteFontFileEnumerator : public IUnknown
1277 {
1278     /// <summary>
1279     /// Advances to the next font file in the collection. When it is first created, the enumerator is positioned
1280     /// before the first element of the collection and the first call to MoveNext advances to the first file.
1281     /// </summary>
1282     /// <param name="hasCurrentFile">Receives the value TRUE if the enumerator advances to a file, or FALSE if
1283     /// the enumerator advanced past the last file in the collection.</param>
1284     /// <returns>
1285     /// Standard HRESULT error code.
1286     /// </returns>
1287     STDMETHOD(MoveNext)(
1288         __out BOOL* hasCurrentFile
1289         ) PURE;
1290 
1291     /// <summary>
1292     /// Gets a reference to the current font file.
1293     /// </summary>
1294     /// <param name="fontFile">Pointer to the newly created font file object.</param>
1295     /// <returns>
1296     /// Standard HRESULT error code.
1297     /// </returns>
1298     STDMETHOD(GetCurrentFontFile)(
1299         __out IDWriteFontFile** fontFile
1300         ) PURE;
1301 };
1302 
1303 /// <summary>
1304 /// Represents a collection of strings indexed by locale name.
1305 /// </summary>
1306 interface DWRITE_DECLARE_INTERFACE("08256209-099a-4b34-b86d-c22b110e7771") IDWriteLocalizedStrings : public IUnknown
1307 {
1308     /// <summary>
1309     /// Gets the number of language/string pairs.
1310     /// </summary>
1311     STDMETHOD_(UINT32, GetCount)() PURE;
1312 
1313     /// <summary>
1314     /// Gets the index of the item with the specified locale name.
1315     /// </summary>
1316     /// <param name="localeName">Locale name to look for.</param>
1317     /// <param name="index">Receives the zero-based index of the locale name/string pair.</param>
1318     /// <param name="exists">Receives TRUE if the locale name exists or FALSE if not.</param>
1319     /// <returns>
1320     /// Standard HRESULT error code. If the specified locale name does not exist, the return value is S_OK,
1321     /// but *index is UINT_MAX and *exists is FALSE.
1322     /// </returns>
1323     STDMETHOD(FindLocaleName)(
1324         __in_z WCHAR const* localeName,
1325         __out UINT32* index,
1326         __out BOOL* exists
1327         ) PURE;
1328 
1329     /// <summary>
1330     /// Gets the length in characters (not including the null terminator) of the locale name with the specified index.
1331     /// </summary>
1332     /// <param name="index">Zero-based index of the locale name.</param>
1333     /// <param name="length">Receives the length in characters, not including the null terminator.</param>
1334     /// <returns>
1335     /// Standard HRESULT error code.
1336     /// </returns>
1337     STDMETHOD(GetLocaleNameLength)(
1338         UINT32 index,
1339         __out UINT32* length
1340         ) PURE;
1341 
1342     /// <summary>
1343     /// Copies the locale name with the specified index to the specified array.
1344     /// </summary>
1345     /// <param name="index">Zero-based index of the locale name.</param>
1346     /// <param name="localeName">Character array that receives the locale name.</param>
1347     /// <param name="size">Size of the array in characters. The size must include space for the terminating
1348     /// null character.</param>
1349     /// <returns>
1350     /// Standard HRESULT error code.
1351     /// </returns>
1352     STDMETHOD(GetLocaleName)(
1353         UINT32 index,
1354         __out_ecount_z(size) WCHAR* localeName,
1355         UINT32 size
1356         ) PURE;
1357 
1358     /// <summary>
1359     /// Gets the length in characters (not including the null terminator) of the string with the specified index.
1360     /// </summary>
1361     /// <param name="index">Zero-based index of the string.</param>
1362     /// <param name="length">Receives the length in characters, not including the null terminator.</param>
1363     /// <returns>
1364     /// Standard HRESULT error code.
1365     /// </returns>
1366     STDMETHOD(GetStringLength)(
1367         UINT32 index,
1368         __out UINT32* length
1369         ) PURE;
1370 
1371     /// <summary>
1372     /// Copies the string with the specified index to the specified array.
1373     /// </summary>
1374     /// <param name="index">Zero-based index of the string.</param>
1375     /// <param name="stringBuffer">Character array that receives the string.</param>
1376     /// <param name="size">Size of the array in characters. The size must include space for the terminating
1377     /// null character.</param>
1378     /// <returns>
1379     /// Standard HRESULT error code.
1380     /// </returns>
1381     STDMETHOD(GetString)(
1382         UINT32 index,
1383         __out_ecount_z(size) WCHAR* stringBuffer,
1384         UINT32 size
1385         ) PURE;
1386 };
1387 
1388 interface IDWriteFontFamily;
1389 interface IDWriteFont;
1390 
1391 /// <summary>
1392 /// The IDWriteFontCollection encapsulates a collection of fonts.
1393 /// </summary>
1394 interface DWRITE_DECLARE_INTERFACE("a84cee02-3eea-4eee-a827-87c1a02a0fcc") IDWriteFontCollection : public IUnknown
1395 {
1396     /// <summary>
1397     /// Gets the number of font families in the collection.
1398     /// </summary>
1399     STDMETHOD_(UINT32, GetFontFamilyCount)() PURE;
1400 
1401     /// <summary>
1402     /// Creates a font family object given a zero-based font family index.
1403     /// </summary>
1404     /// <param name="index">Zero-based index of the font family.</param>
1405     /// <param name="fontFamily">Receives a pointer the newly created font family object.</param>
1406     /// <returns>
1407     /// Standard HRESULT error code.
1408     /// </returns>
1409     STDMETHOD(GetFontFamily)(
1410         UINT32 index,
1411         __out IDWriteFontFamily** fontFamily
1412         ) PURE;
1413 
1414     /// <summary>
1415     /// Finds the font family with the specified family name.
1416     /// </summary>
1417     /// <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>
1418     /// <param name="index">Receives the zero-based index of the matching font family if the family name was found or UINT_MAX otherwise.</param>
1419     /// <param name="exists">Receives TRUE if the family name exists or FALSE otherwise.</param>
1420     /// <returns>
1421     /// 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.
1422     /// </returns>
1423     STDMETHOD(FindFamilyName)(
1424         __in_z WCHAR const* familyName,
1425         __out UINT32* index,
1426         __out BOOL* exists
1427         ) PURE;
1428 
1429     /// <summary>
1430     /// Gets the font object that corresponds to the same physical font as the specified font face object. The specified physical font must belong
1431     /// to the font collection.
1432     /// </summary>
1433     /// <param name="fontFace">Font face object that specifies the physical font.</param>
1434     /// <param name="font">Receives a pointer to the newly created font object if successful or NULL otherwise.</param>
1435     /// <returns>
1436     /// Standard HRESULT error code. If the specified physical font is not part of the font collection the return value is DWRITE_E_NOFONT.
1437     /// </returns>
1438     STDMETHOD(GetFontFromFontFace)(
1439         IDWriteFontFace* fontFace,
1440         __out IDWriteFont** font
1441         ) PURE;
1442 };
1443 
1444 /// <summary>
1445 /// The IDWriteFontList interface represents a list of fonts.
1446 /// </summary>
1447 interface DWRITE_DECLARE_INTERFACE("1a0d8438-1d97-4ec1-aef9-a2fb86ed6acb") IDWriteFontList : public IUnknown
1448 {
1449     /// <summary>
1450     /// Gets the font collection that contains the fonts.
1451     /// </summary>
1452     /// <param name="fontCollection">Receives a pointer to the font collection object.</param>
1453     /// <returns>
1454     /// Standard HRESULT error code.
1455     /// </returns>
1456     STDMETHOD(GetFontCollection)(
1457         __out IDWriteFontCollection** fontCollection
1458         ) PURE;
1459 
1460     /// <summary>
1461     /// Gets the number of fonts in the font list.
1462     /// </summary>
1463     STDMETHOD_(UINT32, GetFontCount)() PURE;
1464 
1465     /// <summary>
1466     /// Gets a font given its zero-based index.
1467     /// </summary>
1468     /// <param name="index">Zero-based index of the font in the font list.</param>
1469     /// <param name="font">Receives a pointer to the newly created font object.</param>
1470     /// <returns>
1471     /// Standard HRESULT error code.
1472     /// </returns>
1473     STDMETHOD(GetFont)(
1474         UINT32 index,
1475         __out IDWriteFont** font
1476         ) PURE;
1477 };
1478 
1479 /// <summary>
1480 /// The IDWriteFontFamily interface represents a set of fonts that share the same design but are differentiated
1481 /// by weight, stretch, and style.
1482 /// </summary>
1483 interface DWRITE_DECLARE_INTERFACE("da20d8ef-812a-4c43-9802-62ec4abd7add") IDWriteFontFamily : public IDWriteFontList
1484 {
1485     /// <summary>
1486     /// Creates an localized strings object that contains the family names for the font family, indexed by locale name.
1487     /// </summary>
1488     /// <param name="names">Receives a pointer to the newly created localized strings object.</param>
1489     /// <returns>
1490     /// Standard HRESULT error code.
1491     /// </returns>
1492     STDMETHOD(GetFamilyNames)(
1493         __out IDWriteLocalizedStrings** names
1494         ) PURE;
1495 
1496     /// <summary>
1497     /// Gets the font that best matches the specified properties.
1498     /// </summary>
1499     /// <param name="weight">Requested font weight.</param>
1500     /// <param name="stretch">Requested font stretch.</param>
1501     /// <param name="style">Requested font style.</param>
1502     /// <param name="matchingFont">Receives a pointer to the newly created font object.</param>
1503     /// <returns>
1504     /// Standard HRESULT error code.
1505     /// </returns>
1506     STDMETHOD(GetFirstMatchingFont)(
1507         DWRITE_FONT_WEIGHT  weight,
1508         DWRITE_FONT_STRETCH stretch,
1509         DWRITE_FONT_STYLE   style,
1510         __out IDWriteFont** matchingFont
1511         ) PURE;
1512 
1513     /// <summary>
1514     /// Gets a list of fonts in the font family ranked in order of how well they match the specified properties.
1515     /// </summary>
1516     /// <param name="weight">Requested font weight.</param>
1517     /// <param name="stretch">Requested font stretch.</param>
1518     /// <param name="style">Requested font style.</param>
1519     /// <param name="matchingFonts">Receives a pointer to the newly created font list object.</param>
1520     /// <returns>
1521     /// Standard HRESULT error code.
1522     /// </returns>
1523     STDMETHOD(GetMatchingFonts)(
1524         DWRITE_FONT_WEIGHT      weight,
1525         DWRITE_FONT_STRETCH     stretch,
1526         DWRITE_FONT_STYLE       style,
1527         __out IDWriteFontList** matchingFonts
1528         ) PURE;
1529 };
1530 
1531 /// <summary>
1532 /// The IDWriteFont interface represents a physical font in a font collection.
1533 /// </summary>
1534 interface DWRITE_DECLARE_INTERFACE("acd16696-8c14-4f5d-877e-fe3fc1d32737") IDWriteFont : public IUnknown
1535 {
1536     /// <summary>
1537     /// Gets the font family to which the specified font belongs.
1538     /// </summary>
1539     /// <param name="fontFamily">Receives a pointer to the font family object.</param>
1540     /// <returns>
1541     /// Standard HRESULT error code.
1542     /// </returns>
1543     STDMETHOD(GetFontFamily)(
1544         __out IDWriteFontFamily** fontFamily
1545         ) PURE;
1546 
1547     /// <summary>
1548     /// Gets the weight of the specified font.
1549     /// </summary>
1550     STDMETHOD_(DWRITE_FONT_WEIGHT, GetWeight)() PURE;
1551 
1552     /// <summary>
1553     /// Gets the stretch (aka. width) of the specified font.
1554     /// </summary>
1555     STDMETHOD_(DWRITE_FONT_STRETCH, GetStretch)() PURE;
1556 
1557     /// <summary>
1558     /// Gets the style (aka. slope) of the specified font.
1559     /// </summary>
1560     STDMETHOD_(DWRITE_FONT_STYLE, GetStyle)() PURE;
1561 
1562     /// <summary>
1563     /// Returns TRUE if the font is a symbol font or FALSE if not.
1564     /// </summary>
1565     STDMETHOD_(BOOL, IsSymbolFont)() PURE;
1566 
1567     /// <summary>
1568     /// Gets a localized strings collection containing the face names for the font (e.g., Regular or Bold), indexed by locale name.
1569     /// </summary>
1570     /// <param name="names">Receives a pointer to the newly created localized strings object.</param>
1571     /// <returns>
1572     /// Standard HRESULT error code.
1573     /// </returns>
1574     STDMETHOD(GetFaceNames)(
1575         __out IDWriteLocalizedStrings** names
1576         ) PURE;
1577 
1578     /// <summary>
1579     /// Gets a localized strings collection containing the specified informational strings, indexed by locale name.
1580     /// </summary>
1581     /// <param name="informationalStringID">Identifies the string to get.</param>
1582     /// <param name="informationalStrings">Receives a pointer to the newly created localized strings object.</param>
1583     /// <param name="exists">Receives the value TRUE if the font contains the specified string ID or FALSE if not.</param>
1584     /// <returns>
1585     /// Standard HRESULT error code. If the font does not contain the specified string, the return value is S_OK but
1586     /// informationalStrings receives a NULL pointer and exists receives the value FALSE.
1587     /// </returns>
1588     STDMETHOD(GetInformationalStrings)(
1589         DWRITE_INFORMATIONAL_STRING_ID informationalStringID,
1590         __out IDWriteLocalizedStrings** informationalStrings,
1591         __out BOOL* exists
1592         ) PURE;
1593 
1594     /// <summary>
1595     /// Gets a value that indicates what simulation are applied to the specified font.
1596     /// </summary>
1597     STDMETHOD_(DWRITE_FONT_SIMULATIONS, GetSimulations)() PURE;
1598 
1599     /// <summary>
1600     /// Gets the metrics for the font.
1601     /// </summary>
1602     /// <param name="fontMetrics">Receives the font metrics.</param>
1603     STDMETHOD_(void, GetMetrics)(
1604         __out DWRITE_FONT_METRICS* fontMetrics
1605         ) PURE;
1606 
1607     /// <summary>
1608     /// Determines whether the font supports the specified character.
1609     /// </summary>
1610     /// <param name="unicodeValue">Unicode (UCS-4) character value.</param>
1611     /// <param name="exists">Receives the value TRUE if the font supports the specified character or FALSE if not.</param>
1612     /// <returns>
1613     /// Standard HRESULT error code.
1614     /// </returns>
1615     STDMETHOD(HasCharacter)(
1616         UINT32 unicodeValue,
1617         __out BOOL* exists
1618         ) PURE;
1619 
1620     /// <summary>
1621     /// Creates a font face object for the font.
1622     /// </summary>
1623     /// <param name="fontFace">Receives a pointer to the newly created font face object.</param>
1624     /// <returns>
1625     /// Standard HRESULT error code.
1626     /// </returns>
1627     STDMETHOD(CreateFontFace)(
1628         __out IDWriteFontFace** fontFace
1629         ) PURE;
1630 };
1631 
1632 /// <summary>
1633 /// Direction for how reading progresses.
1634 /// </summary>
1635 enum DWRITE_READING_DIRECTION
1636 {
1637     /// <summary>
1638     /// Reading progresses from left to right.
1639     /// </summary>
1640     DWRITE_READING_DIRECTION_LEFT_TO_RIGHT,
1641 
1642     /// <summary>
1643     /// Reading progresses from right to left.
1644     /// </summary>
1645     DWRITE_READING_DIRECTION_RIGHT_TO_LEFT
1646 };
1647 
1648 /// <summary>
1649 /// Direction for how lines of text are placed relative to one another.
1650 /// </summary>
1651 enum DWRITE_FLOW_DIRECTION
1652 {
1653     /// <summary>
1654     /// Text lines are placed from top to bottom.
1655     /// </summary>
1656     DWRITE_FLOW_DIRECTION_TOP_TO_BOTTOM
1657 };
1658 
1659 /// <summary>
1660 /// Alignment of paragraph text along the reading direction axis relative to
1661 /// the leading and trailing edge of the layout box.
1662 /// </summary>
1663 enum DWRITE_TEXT_ALIGNMENT
1664 {
1665     /// <summary>
1666     /// The leading edge of the paragraph text is aligned to the layout box's leading edge.
1667     /// </summary>
1668     DWRITE_TEXT_ALIGNMENT_LEADING,
1669 
1670     /// <summary>
1671     /// The trailing edge of the paragraph text is aligned to the layout box's trailing edge.
1672     /// </summary>
1673     DWRITE_TEXT_ALIGNMENT_TRAILING,
1674 
1675     /// <summary>
1676     /// The center of the paragraph text is aligned to the center of the layout box.
1677     /// </summary>
1678     DWRITE_TEXT_ALIGNMENT_CENTER
1679 };
1680 
1681 /// <summary>
1682 /// Alignment of paragraph text along the flow direction axis relative to the
1683 /// flow's beginning and ending edge of the layout box.
1684 /// </summary>
1685 enum DWRITE_PARAGRAPH_ALIGNMENT
1686 {
1687     /// <summary>
1688     /// The first line of paragraph is aligned to the flow's beginning edge of the layout box.
1689     /// </summary>
1690     DWRITE_PARAGRAPH_ALIGNMENT_NEAR,
1691 
1692     /// <summary>
1693     /// The last line of paragraph is aligned to the flow's ending edge of the layout box.
1694     /// </summary>
1695     DWRITE_PARAGRAPH_ALIGNMENT_FAR,
1696 
1697     /// <summary>
1698     /// The center of the paragraph is aligned to the center of the flow of the layout box.
1699     /// </summary>
1700     DWRITE_PARAGRAPH_ALIGNMENT_CENTER
1701 };
1702 
1703 /// <summary>
1704 /// Word wrapping in multiline paragraph.
1705 /// </summary>
1706 enum DWRITE_WORD_WRAPPING
1707 {
1708     /// <summary>
1709     /// Words are broken across lines to avoid text overflowing the layout box.
1710     /// </summary>
1711     DWRITE_WORD_WRAPPING_WRAP,
1712 
1713     /// <summary>
1714     /// Words are kept within the same line even when it overflows the layout box.
1715     /// This option is often used with scrolling to reveal overflow text.
1716     /// </summary>
1717     DWRITE_WORD_WRAPPING_NO_WRAP
1718 };
1719 
1720 /// <summary>
1721 /// The method used for line spacing in layout.
1722 /// </summary>
1723 enum DWRITE_LINE_SPACING_METHOD
1724 {
1725     /// <summary>
1726     /// Line spacing depends solely on the content, growing to accomodate the size of fonts and inline objects.
1727     /// </summary>
1728     DWRITE_LINE_SPACING_METHOD_DEFAULT,
1729 
1730     /// <summary>
1731     /// Lines are explicitly set to uniform spacing, regardless of contained font sizes.
1732     /// This can be useful to avoid the uneven appearance that can occur from font fallback.
1733     /// </summary>
1734     DWRITE_LINE_SPACING_METHOD_UNIFORM
1735 };
1736 
1737 /// <summary>
1738 /// Text granularity used to trim text overflowing the layout box.
1739 /// </summary>
1740 enum DWRITE_TRIMMING_GRANULARITY
1741 {
1742     /// <summary>
1743     /// No trimming occurs. Text flows beyond the layout width.
1744     /// </summary>
1745     DWRITE_TRIMMING_GRANULARITY_NONE,
1746 
1747     /// <summary>
1748     /// Trimming occurs at character cluster boundary.
1749     /// </summary>
1750     DWRITE_TRIMMING_GRANULARITY_CHARACTER,
1751 
1752     /// <summary>
1753     /// Trimming occurs at word boundary.
1754     /// </summary>
1755     DWRITE_TRIMMING_GRANULARITY_WORD
1756 };
1757 
1758 /// <summary>
1759 /// Typographic feature of text supplied by the font.
1760 /// </summary>
1761 enum DWRITE_FONT_FEATURE_TAG
1762 {
1763     DWRITE_FONT_FEATURE_TAG_ALTERNATIVE_FRACTIONS               = 0x63726661, // 'afrc'
1764     DWRITE_FONT_FEATURE_TAG_PETITE_CAPITALS_FROM_CAPITALS       = 0x63703263, // 'c2pc'
1765     DWRITE_FONT_FEATURE_TAG_SMALL_CAPITALS_FROM_CAPITALS        = 0x63733263, // 'c2sc'
1766     DWRITE_FONT_FEATURE_TAG_CONTEXTUAL_ALTERNATES               = 0x746c6163, // 'calt'
1767     DWRITE_FONT_FEATURE_TAG_CASE_SENSITIVE_FORMS                = 0x65736163, // 'case'
1768     DWRITE_FONT_FEATURE_TAG_GLYPH_COMPOSITION_DECOMPOSITION     = 0x706d6363, // 'ccmp'
1769     DWRITE_FONT_FEATURE_TAG_CONTEXTUAL_LIGATURES                = 0x67696c63, // 'clig'
1770     DWRITE_FONT_FEATURE_TAG_CAPITAL_SPACING                     = 0x70737063, // 'cpsp'
1771     DWRITE_FONT_FEATURE_TAG_CONTEXTUAL_SWASH                    = 0x68777363, // 'cswh'
1772     DWRITE_FONT_FEATURE_TAG_CURSIVE_POSITIONING                 = 0x73727563, // 'curs'
1773     DWRITE_FONT_FEATURE_TAG_DEFAULT                             = 0x746c6664, // 'dflt'
1774     DWRITE_FONT_FEATURE_TAG_DISCRETIONARY_LIGATURES             = 0x67696c64, // 'dlig'
1775     DWRITE_FONT_FEATURE_TAG_EXPERT_FORMS                        = 0x74707865, // 'expt'
1776     DWRITE_FONT_FEATURE_TAG_FRACTIONS                           = 0x63617266, // 'frac'
1777     DWRITE_FONT_FEATURE_TAG_FULL_WIDTH                          = 0x64697766, // 'fwid'
1778     DWRITE_FONT_FEATURE_TAG_HALF_FORMS                          = 0x666c6168, // 'half'
1779     DWRITE_FONT_FEATURE_TAG_HALANT_FORMS                        = 0x6e6c6168, // 'haln'
1780     DWRITE_FONT_FEATURE_TAG_ALTERNATE_HALF_WIDTH                = 0x746c6168, // 'halt'
1781     DWRITE_FONT_FEATURE_TAG_HISTORICAL_FORMS                    = 0x74736968, // 'hist'
1782     DWRITE_FONT_FEATURE_TAG_HORIZONTAL_KANA_ALTERNATES          = 0x616e6b68, // 'hkna'
1783     DWRITE_FONT_FEATURE_TAG_HISTORICAL_LIGATURES                = 0x67696c68, // 'hlig'
1784     DWRITE_FONT_FEATURE_TAG_HALF_WIDTH                          = 0x64697768, // 'hwid'
1785     DWRITE_FONT_FEATURE_TAG_HOJO_KANJI_FORMS                    = 0x6f6a6f68, // 'hojo'
1786     DWRITE_FONT_FEATURE_TAG_JIS04_FORMS                         = 0x3430706a, // 'jp04'
1787     DWRITE_FONT_FEATURE_TAG_JIS78_FORMS                         = 0x3837706a, // 'jp78'
1788     DWRITE_FONT_FEATURE_TAG_JIS83_FORMS                         = 0x3338706a, // 'jp83'
1789     DWRITE_FONT_FEATURE_TAG_JIS90_FORMS                         = 0x3039706a, // 'jp90'
1790     DWRITE_FONT_FEATURE_TAG_KERNING                             = 0x6e72656b, // 'kern'
1791     DWRITE_FONT_FEATURE_TAG_STANDARD_LIGATURES                  = 0x6167696c, // 'liga'
1792     DWRITE_FONT_FEATURE_TAG_LINING_FIGURES                      = 0x6d756e6c, // 'lnum'
1793     DWRITE_FONT_FEATURE_TAG_LOCALIZED_FORMS                     = 0x6c636f6c, // 'locl'
1794     DWRITE_FONT_FEATURE_TAG_MARK_POSITIONING                    = 0x6b72616d, // 'mark'
1795     DWRITE_FONT_FEATURE_TAG_MATHEMATICAL_GREEK                  = 0x6b72676d, // 'mgrk'
1796     DWRITE_FONT_FEATURE_TAG_MARK_TO_MARK_POSITIONING            = 0x6b6d6b6d, // 'mkmk'
1797     DWRITE_FONT_FEATURE_TAG_ALTERNATE_ANNOTATION_FORMS          = 0x746c616e, // 'nalt'
1798     DWRITE_FONT_FEATURE_TAG_NLC_KANJI_FORMS                     = 0x6b636c6e, // 'nlck'
1799     DWRITE_FONT_FEATURE_TAG_OLD_STYLE_FIGURES                   = 0x6d756e6f, // 'onum'
1800     DWRITE_FONT_FEATURE_TAG_ORDINALS                            = 0x6e64726f, // 'ordn'
1801     DWRITE_FONT_FEATURE_TAG_PROPORTIONAL_ALTERNATE_WIDTH        = 0x746c6170, // 'palt'
1802     DWRITE_FONT_FEATURE_TAG_PETITE_CAPITALS                     = 0x70616370, // 'pcap'
1803     DWRITE_FONT_FEATURE_TAG_PROPORTIONAL_FIGURES                = 0x6d756e70, // 'pnum'
1804     DWRITE_FONT_FEATURE_TAG_PROPORTIONAL_WIDTHS                 = 0x64697770, // 'pwid'
1805     DWRITE_FONT_FEATURE_TAG_QUARTER_WIDTHS                      = 0x64697771, // 'qwid'
1806     DWRITE_FONT_FEATURE_TAG_REQUIRED_LIGATURES                  = 0x67696c72, // 'rlig'
1807     DWRITE_FONT_FEATURE_TAG_RUBY_NOTATION_FORMS                 = 0x79627572, // 'ruby'
1808     DWRITE_FONT_FEATURE_TAG_STYLISTIC_ALTERNATES                = 0x746c6173, // 'salt'
1809     DWRITE_FONT_FEATURE_TAG_SCIENTIFIC_INFERIORS                = 0x666e6973, // 'sinf'
1810     DWRITE_FONT_FEATURE_TAG_SMALL_CAPITALS                      = 0x70636d73, // 'smcp'
1811     DWRITE_FONT_FEATURE_TAG_SIMPLIFIED_FORMS                    = 0x6c706d73, // 'smpl'
1812     DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_1                     = 0x31307373, // 'ss01'
1813     DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_2                     = 0x32307373, // 'ss02'
1814     DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_3                     = 0x33307373, // 'ss03'
1815     DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_4                     = 0x34307373, // 'ss04'
1816     DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_5                     = 0x35307373, // 'ss05'
1817     DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_6                     = 0x36307373, // 'ss06'
1818     DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_7                     = 0x37307373, // 'ss07'
1819     DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_8                     = 0x38307373, // 'ss08'
1820     DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_9                     = 0x39307373, // 'ss09'
1821     DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_10                    = 0x30317373, // 'ss10'
1822     DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_11                    = 0x31317373, // 'ss11'
1823     DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_12                    = 0x32317373, // 'ss12'
1824     DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_13                    = 0x33317373, // 'ss13'
1825     DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_14                    = 0x34317373, // 'ss14'
1826     DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_15                    = 0x35317373, // 'ss15'
1827     DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_16                    = 0x36317373, // 'ss16'
1828     DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_17                    = 0x37317373, // 'ss17'
1829     DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_18                    = 0x38317373, // 'ss18'
1830     DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_19                    = 0x39317373, // 'ss19'
1831     DWRITE_FONT_FEATURE_TAG_STYLISTIC_SET_20                    = 0x30327373, // 'ss20'
1832     DWRITE_FONT_FEATURE_TAG_SUBSCRIPT                           = 0x73627573, // 'subs'
1833     DWRITE_FONT_FEATURE_TAG_SUPERSCRIPT                         = 0x73707573, // 'sups'
1834     DWRITE_FONT_FEATURE_TAG_SWASH                               = 0x68737773, // 'swsh'
1835     DWRITE_FONT_FEATURE_TAG_TITLING                             = 0x6c746974, // 'titl'
1836     DWRITE_FONT_FEATURE_TAG_TRADITIONAL_NAME_FORMS              = 0x6d616e74, // 'tnam'
1837     DWRITE_FONT_FEATURE_TAG_TABULAR_FIGURES                     = 0x6d756e74, // 'tnum'
1838     DWRITE_FONT_FEATURE_TAG_TRADITIONAL_FORMS                   = 0x64617274, // 'trad'
1839     DWRITE_FONT_FEATURE_TAG_THIRD_WIDTHS                        = 0x64697774, // 'twid'
1840     DWRITE_FONT_FEATURE_TAG_UNICASE                             = 0x63696e75, // 'unic'
1841     DWRITE_FONT_FEATURE_TAG_SLASHED_ZERO                        = 0x6f72657a, // 'zero'
1842 };
1843 
1844 /// <summary>
1845 /// The DWRITE_TEXT_RANGE structure specifies a range of text positions where format is applied.
1846 /// </summary>
1847 struct DWRITE_TEXT_RANGE
1848 {
1849     /// <summary>
1850     /// The start text position of the range.
1851     /// </summary>
1852     UINT32 startPosition;
1853 
1854     /// <summary>
1855     /// The number of text positions in the range.
1856     /// </summary>
1857     UINT32 length;
1858 };
1859 
1860 /// <summary>
1861 /// The DWRITE_FONT_FEATURE structure specifies properties used to identify and execute typographic feature in the font.
1862 /// </summary>
1863 struct DWRITE_FONT_FEATURE
1864 {
1865     /// <summary>
1866     /// The feature OpenType name identifier.
1867     /// </summary>
1868     DWRITE_FONT_FEATURE_TAG nameTag;
1869 
1870     /// <summary>
1871     /// Execution parameter of the feature.
1872     /// </summary>
1873     /// <remarks>
1874     /// The parameter should be non-zero to enable the feature.  Once enabled, a feature can't be disabled again within
1875     /// the same range.  Features requiring a selector use this value to indicate the selector index.
1876     /// </remarks>
1877     UINT32 parameter;
1878 };
1879 
1880 /// <summary>
1881 /// Defines a set of typographic features to be applied during shaping.
1882 /// Notice the character range which this feature list spans is specified
1883 /// as a separate parameter to GetGlyphs.
1884 /// </summary>
1885 struct DWRITE_TYPOGRAPHIC_FEATURES
1886 {
1887     /// <summary>
1888     /// Array of font features.
1889     /// </summary>
1890     __field_ecount(featureCount) DWRITE_FONT_FEATURE* features;
1891 
1892     /// <summary>
1893     /// The number of features.
1894     /// </summary>
1895     UINT32 featureCount;
1896 };
1897 
1898 /// <summary>
1899 /// The DWRITE_TRIMMING structure specifies the trimming option for text overflowing the layout box.
1900 /// </summary>
1901 struct DWRITE_TRIMMING
1902 {
1903     /// <summary>
1904     /// Text granularity of which trimming applies.
1905     /// </summary>
1906     DWRITE_TRIMMING_GRANULARITY granularity;
1907 
1908     /// <summary>
1909     /// Character code used as the delimiter signaling the beginning of the portion of text to be preserved,
1910     /// most useful for path ellipsis, where the delimeter would be a slash.
1911     /// </summary>
1912     UINT32 delimiter;
1913 
1914     /// <summary>
1915     /// How many occurences of the delimiter to step back.
1916     /// </summary>
1917     UINT32 delimiterCount;
1918 };
1919 
1920 
1921 interface IDWriteTypography;
1922 interface IDWriteInlineObject;
1923 
1924 /// <summary>
1925 /// The format of text used for text layout purpose.
1926 /// </summary>
1927 /// <remarks>
1928 /// This object may not be thread-safe and it may carry the state of text format change.
1929 /// </remarks>
1930 interface DWRITE_DECLARE_INTERFACE("9c906818-31d7-4fd3-a151-7c5e225db55a") IDWriteTextFormat : public IUnknown
1931 {
1932     /// <summary>
1933     /// Set alignment option of text relative to layout box's leading and trailing edge.
1934     /// </summary>
1935     /// <param name="textAlignment">Text alignment option</param>
1936     /// <returns>
1937     /// Standard HRESULT error code.
1938     /// </returns>
1939     STDMETHOD(SetTextAlignment)(
1940         DWRITE_TEXT_ALIGNMENT textAlignment
1941         ) PURE;
1942 
1943     /// <summary>
1944     /// Set alignment option of paragraph relative to layout box's top and bottom edge.
1945     /// </summary>
1946     /// <param name="paragraphAlignment">Paragraph alignment option</param>
1947     /// <returns>
1948     /// Standard HRESULT error code.
1949     /// </returns>
1950     STDMETHOD(SetParagraphAlignment)(
1951         DWRITE_PARAGRAPH_ALIGNMENT paragraphAlignment
1952         ) PURE;
1953 
1954     /// <summary>
1955     /// Set word wrapping option.
1956     /// </summary>
1957     /// <param name="wordWrapping">Word wrapping option</param>
1958     /// <returns>
1959     /// Standard HRESULT error code.
1960     /// </returns>
1961     STDMETHOD(SetWordWrapping)(
1962         DWRITE_WORD_WRAPPING wordWrapping
1963         ) PURE;
1964 
1965     /// <summary>
1966     /// Set paragraph reading direction.
1967     /// </summary>
1968     /// <param name="readingDirection">Text reading direction</param>
1969     /// <returns>
1970     /// Standard HRESULT error code.
1971     /// </returns>
1972     STDMETHOD(SetReadingDirection)(
1973         DWRITE_READING_DIRECTION readingDirection
1974         ) PURE;
1975 
1976     /// <summary>
1977     /// Set paragraph flow direction.
1978     /// </summary>
1979     /// <param name="flowDirection">Paragraph flow direction</param>
1980     /// <returns>
1981     /// Standard HRESULT error code.
1982     /// </returns>
1983     STDMETHOD(SetFlowDirection)(
1984         DWRITE_FLOW_DIRECTION flowDirection
1985         ) PURE;
1986 
1987     /// <summary>
1988     /// Set incremental tab stop position.
1989     /// </summary>
1990     /// <param name="incrementalTabStop">The incremental tab stop value</param>
1991     /// <returns>
1992     /// Standard HRESULT error code.
1993     /// </returns>
1994     STDMETHOD(SetIncrementalTabStop)(
1995         FLOAT incrementalTabStop
1996         ) PURE;
1997 
1998     /// <summary>
1999     /// Set trimming options for any trailing text exceeding the layout width
2000     /// or for any far text exceeding the layout height.
2001     /// </summary>
2002     /// <param name="trimmingOptions">Text trimming options.</param>
2003     /// <param name="trimmingSign">Application-defined omission sign. This parameter may be NULL if no trimming sign is desired.</param>
2004     /// <remarks>
2005     /// Any inline object can be used for the trimming sign, but CreateEllipsisTrimmingSign
2006     /// provides a typical ellipsis symbol. Trimming is also useful vertically for hiding
2007     /// partial lines.
2008     /// </remarks>
2009     /// <returns>
2010     /// Standard HRESULT error code.
2011     /// </returns>
2012     STDMETHOD(SetTrimming)(
2013         __in DWRITE_TRIMMING const* trimmingOptions,
2014         IDWriteInlineObject* trimmingSign
2015         ) PURE;
2016 
2017     /// <summary>
2018     /// Set line spacing.
2019     /// </summary>
2020     /// <param name="lineSpacingMethod">How to determine line height.</param>
2021     /// <param name="lineSpacing">The line height, or rather distance between one baseline to another.</param>
2022     /// <param name="baseline">Distance from top of line to baseline. A reasonable ratio to lineSpacing is 80%.</param>
2023     /// <remarks>
2024     /// For the default method, spacing depends solely on the content.
2025     /// For uniform spacing, the given line height will override the content.
2026     /// </remarks>
2027     /// <returns>
2028     /// Standard HRESULT error code.
2029     /// </returns>
2030     STDMETHOD(SetLineSpacing)(
2031         DWRITE_LINE_SPACING_METHOD lineSpacingMethod,
2032         FLOAT lineSpacing,
2033         FLOAT baseline
2034         ) PURE;
2035 
2036     /// <summary>
2037     /// Get alignment option of text relative to layout box's leading and trailing edge.
2038     /// </summary>
2039     STDMETHOD_(DWRITE_TEXT_ALIGNMENT, GetTextAlignment)() PURE;
2040 
2041     /// <summary>
2042     /// Get alignment option of paragraph relative to layout box's top and bottom edge.
2043     /// </summary>
2044     STDMETHOD_(DWRITE_PARAGRAPH_ALIGNMENT, GetParagraphAlignment)() PURE;
2045 
2046     /// <summary>
2047     /// Get word wrapping option.
2048     /// </summary>
2049     STDMETHOD_(DWRITE_WORD_WRAPPING, GetWordWrapping)() PURE;
2050 
2051     /// <summary>
2052     /// Get paragraph reading direction.
2053     /// </summary>
2054     STDMETHOD_(DWRITE_READING_DIRECTION, GetReadingDirection)() PURE;
2055 
2056     /// <summary>
2057     /// Get paragraph flow direction.
2058     /// </summary>
2059     STDMETHOD_(DWRITE_FLOW_DIRECTION, GetFlowDirection)() PURE;
2060 
2061     /// <summary>
2062     /// Get incremental tab stop position.
2063     /// </summary>
2064     STDMETHOD_(FLOAT, GetIncrementalTabStop)() PURE;
2065 
2066     /// <summary>
2067     /// Get trimming options for text overflowing the layout width.
2068     /// </summary>
2069     /// <param name="trimmingOptions">Text trimming options.</param>
2070     /// <param name="trimmingSign">Trimming omission sign. This parameter may be NULL.</param>
2071     /// <returns>
2072     /// Standard HRESULT error code.
2073     /// </returns>
2074     STDMETHOD(GetTrimming)(
2075         __out DWRITE_TRIMMING* trimmingOptions,
2076         __out IDWriteInlineObject** trimmingSign
2077         ) PURE;
2078 
2079     /// <summary>
2080     /// Get line spacing.
2081     /// </summary>
2082     /// <param name="lineSpacingMethod">How line height is determined.</param>
2083     /// <param name="lineSpacing">The line height, or rather distance between one baseline to another.</param>
2084     /// <param name="baseline">Distance from top of line to baseline.</param>
2085     /// <returns>
2086     /// Standard HRESULT error code.
2087     /// </returns>
2088     STDMETHOD(GetLineSpacing)(
2089         __out DWRITE_LINE_SPACING_METHOD* lineSpacingMethod,
2090         __out FLOAT* lineSpacing,
2091         __out FLOAT* baseline
2092         ) PURE;
2093 
2094     /// <summary>
2095     /// Get the font collection.
2096     /// </summary>
2097     /// <param name="fontCollection">The current font collection.</param>
2098     /// <returns>
2099     /// Standard HRESULT error code.
2100     /// </returns>
2101     STDMETHOD(GetFontCollection)(
2102         __out IDWriteFontCollection** fontCollection
2103         ) PURE;
2104 
2105     /// <summary>
2106     /// Get the length of the font family name, in characters, not including the terminating NULL character.
2107     /// </summary>
2108     STDMETHOD_(UINT32, GetFontFamilyNameLength)() PURE;
2109 
2110     /// <summary>
2111     /// Get a copy of the font family name.
2112     /// </summary>
2113     /// <param name="fontFamilyName">Character array that receives the current font family name</param>
2114     /// <param name="nameSize">Size of the character array in character count including the terminated NULL character.</param>
2115     /// <returns>
2116     /// Standard HRESULT error code.
2117     /// </returns>
2118     STDMETHOD(GetFontFamilyName)(
2119         __out_ecount_z(nameSize) WCHAR* fontFamilyName,
2120         UINT32 nameSize
2121         ) PURE;
2122 
2123     /// <summary>
2124     /// Get the font weight.
2125     /// </summary>
2126     STDMETHOD_(DWRITE_FONT_WEIGHT, GetFontWeight)() PURE;
2127 
2128     /// <summary>
2129     /// Get the font style.
2130     /// </summary>
2131     STDMETHOD_(DWRITE_FONT_STYLE, GetFontStyle)() PURE;
2132 
2133     /// <summary>
2134     /// Get the font stretch.
2135     /// </summary>
2136     STDMETHOD_(DWRITE_FONT_STRETCH, GetFontStretch)() PURE;
2137 
2138     /// <summary>
2139     /// Get the font em height.
2140     /// </summary>
2141     STDMETHOD_(FLOAT, GetFontSize)() PURE;
2142 
2143     /// <summary>
2144     /// Get the length of the locale name, in characters, not including the terminating NULL character.
2145     /// </summary>
2146     STDMETHOD_(UINT32, GetLocaleNameLength)() PURE;
2147 
2148     /// <summary>
2149     /// Get a copy of the locale name.
2150     /// </summary>
2151     /// <param name="localeName">Character array that receives the current locale name</param>
2152     /// <param name="nameSize">Size of the character array in character count including the terminated NULL character.</param>
2153     /// <returns>
2154     /// Standard HRESULT error code.
2155     /// </returns>
2156     STDMETHOD(GetLocaleName)(
2157         __out_ecount_z(nameSize) WCHAR* localeName,
2158         UINT32 nameSize
2159         ) PURE;
2160 };
2161 
2162 
2163 /// <summary>
2164 /// Font typography setting.
2165 /// </summary>
2166 interface DWRITE_DECLARE_INTERFACE("55f1112b-1dc2-4b3c-9541-f46894ed85b6") IDWriteTypography : public IUnknown
2167 {
2168     /// <summary>
2169     /// Add font feature.
2170     /// </summary>
2171     /// <param name="fontFeature">The font feature to add.</param>
2172     /// <returns>
2173     /// Standard HRESULT error code.
2174     /// </returns>
2175     STDMETHOD(AddFontFeature)(
2176         DWRITE_FONT_FEATURE fontFeature
2177         ) PURE;
2178 
2179     /// <summary>
2180     /// Get the number of font features.
2181     /// </summary>
2182     STDMETHOD_(UINT32, GetFontFeatureCount)() PURE;
2183 
2184     /// <summary>
2185     /// Get the font feature at the specified index.
2186     /// </summary>
2187     /// <param name="fontFeatureIndex">The zero-based index of the font feature to get.</param>
2188     /// <param name="fontFeature">The font feature.</param>
2189     /// <returns>
2190     /// Standard HRESULT error code.
2191     /// </returns>
2192     STDMETHOD(GetFontFeature)(
2193         UINT32 fontFeatureIndex,
2194         __out DWRITE_FONT_FEATURE* fontFeature
2195         ) PURE;
2196 };
2197 
2198 enum DWRITE_SCRIPT_SHAPES
2199 {
2200     /// <summary>
2201     /// No additional shaping requirement. Text is shaped with the writing system default behavior.
2202     /// </summary>
2203     DWRITE_SCRIPT_SHAPES_DEFAULT = 0,
2204 
2205     /// <summary>
2206     /// Text should leave no visual on display i.e. control or format control characters.
2207     /// </summary>
2208     DWRITE_SCRIPT_SHAPES_NO_VISUAL = 1
2209 };
2210 
2211 #ifdef DEFINE_ENUM_FLAG_OPERATORS
2212 DEFINE_ENUM_FLAG_OPERATORS(DWRITE_SCRIPT_SHAPES);
2213 #endif
2214 
2215 /// <summary>
2216 /// Association of text and its writing system script as well as some display attributes.
2217 /// </summary>
2218 struct DWRITE_SCRIPT_ANALYSIS
2219 {
2220     /// <summary>
2221     /// Zero-based index representation of writing system script.
2222     /// </summary>
2223     UINT16 script;
2224 
2225     /// <summary>
2226     /// Additional shaping requirement of text.
2227     /// </summary>
2228     DWRITE_SCRIPT_SHAPES shapes;
2229 };
2230 
2231 /// <summary>
2232 /// Condition at the edges of inline object or text used to determine
2233 /// line-breaking behavior.
2234 /// </summary>
2235 enum DWRITE_BREAK_CONDITION
2236 {
2237     /// <summary>
2238     /// Whether a break is allowed is determined by the condition of the
2239     /// neighboring text span or inline object.
2240     /// </summary>
2241     DWRITE_BREAK_CONDITION_NEUTRAL,
2242 
2243     /// <summary>
2244     /// A break is allowed, unless overruled by the condition of the
2245     /// neighboring text span or inline object, either prohibited by a
2246     /// May Not or forced by a Must.
2247     /// </summary>
2248     DWRITE_BREAK_CONDITION_CAN_BREAK,
2249 
2250     /// <summary>
2251     /// There should be no break, unless overruled by a Must condition from
2252     /// the neighboring text span or inline object.
2253     /// </summary>
2254     DWRITE_BREAK_CONDITION_MAY_NOT_BREAK,
2255 
2256     /// <summary>
2257     /// The break must happen, regardless of the condition of the adjacent
2258     /// text span or inline object.
2259     /// </summary>
2260     DWRITE_BREAK_CONDITION_MUST_BREAK
2261 };
2262 
2263 /// <summary>
2264 /// Line breakpoint characteristics of a character.
2265 /// </summary>
2266 struct DWRITE_LINE_BREAKPOINT
2267 {
2268     /// <summary>
2269     /// Breaking condition before the character.
2270     /// </summary>
2271     UINT8 breakConditionBefore  : 2;
2272 
2273     /// <summary>
2274     /// Breaking condition after the character.
2275     /// </summary>
2276     UINT8 breakConditionAfter   : 2;
2277 
2278     /// <summary>
2279     /// The character is some form of whitespace, which may be meaningful
2280     /// for justification.
2281     /// </summary>
2282     UINT8 isWhitespace          : 1;
2283 
2284     /// <summary>
2285     /// The character is a soft hyphen, often used to indicate hyphenation
2286     /// points inside words.
2287     /// </summary>
2288     UINT8 isSoftHyphen          : 1;
2289 
2290     UINT8 padding               : 2;
2291 };
2292 
2293 /// <summary>
2294 /// How to apply number substitution on digits and related punctuation.
2295 /// </summary>
2296 enum DWRITE_NUMBER_SUBSTITUTION_METHOD
2297 {
2298     /// <summary>
2299     /// Specifies that the substitution method should be determined based
2300     /// on LOCALE_IDIGITSUBSTITUTION value of the specified text culture.
2301     /// </summary>
2302     DWRITE_NUMBER_SUBSTITUTION_METHOD_FROM_CULTURE,
2303 
2304     /// <summary>
2305     /// If the culture is Arabic or Farsi, specifies that the number shape
2306     /// depend on the context. Either traditional or nominal number shape
2307     /// are used depending on the nearest preceding strong character or (if
2308     /// there is none) the reading direction of the paragraph.
2309     /// </summary>
2310     DWRITE_NUMBER_SUBSTITUTION_METHOD_CONTEXTUAL,
2311 
2312     /// <summary>
2313     /// Specifies that code points 0x30-0x39 are always rendered as nominal numeral
2314     /// shapes (ones of the European number), i.e., no substitution is performed.
2315     /// </summary>
2316     DWRITE_NUMBER_SUBSTITUTION_METHOD_NONE,
2317 
2318     /// <summary>
2319     /// Specifies that number are rendered using the national number shape
2320     /// as specified by the LOCALE_SNATIVEDIGITS value of the specified text culture.
2321     /// </summary>
2322     DWRITE_NUMBER_SUBSTITUTION_METHOD_NATIONAL,
2323 
2324     /// <summary>
2325     /// Specifies that number are rendered using the traditional shape
2326     /// for the specified culture. For most cultures, this is the same as
2327     /// NativeNational. However, NativeNational results in Latin number
2328     /// for some Arabic cultures, whereas this value results in Arabic
2329     /// number for all Arabic cultures.
2330     /// </summary>
2331     DWRITE_NUMBER_SUBSTITUTION_METHOD_TRADITIONAL
2332 };
2333 
2334 /// <summary>
2335 /// Holds the appropriate digits and numeric punctuation for a given locale.
2336 /// </summary>
2337 interface DECLSPEC_UUID("14885CC9-BAB0-4f90-B6ED-5C366A2CD03D") DECLSPEC_NOVTABLE IDWriteNumberSubstitution : public IUnknown
2338 {
2339 };
2340 
2341 /// <summary>
2342 /// Shaping output properties per input character.
2343 /// </summary>
2344 struct DWRITE_SHAPING_TEXT_PROPERTIES
2345 {
2346     /// <summary>
2347     /// This character can be shaped independently from the others
2348     /// (usually set for the space character).
2349     /// </summary>
2350     UINT16  isShapedAlone       : 1;
2351 
2352     /// <summary>
2353     /// Reserved for use by shaping engine.
2354     /// </summary>
2355     UINT16  reserved            : 15;
2356 };
2357 
2358 /// <summary>
2359 /// Shaping output properties per output glyph.
2360 /// </summary>
2361 struct DWRITE_SHAPING_GLYPH_PROPERTIES
2362 {
2363     /// <summary>
2364     /// Justification class, whether to use spacing, kashidas, or
2365     /// another method. This exists for backwards compatibility
2366     /// with Uniscribe's SCRIPT_JUSTIFY enum.
2367     /// </summary>
2368     UINT16  justification       : 4;
2369 
2370     /// <summary>
2371     /// Indicates glyph is the first of a cluster.
2372     /// </summary>
2373     UINT16  isClusterStart      : 1;
2374 
2375     /// <summary>
2376     /// Glyph is a diacritic.
2377     /// </summary>
2378     UINT16  isDiacritic         : 1;
2379 
2380     /// <summary>
2381     /// Glyph has no width, blank, ZWJ, ZWNJ etc.
2382     /// </summary>
2383     UINT16  isZeroWidthSpace    : 1;
2384 
2385     /// <summary>
2386     /// Reserved for use by shaping engine.
2387     /// </summary>
2388     UINT16  reserved            : 9;
2389 };
2390 
2391 /// <summary>
2392 /// The interface implemented by the text analyzer's client to provide text to
2393 /// the analyzer. It allows the separation between the logical view of text as
2394 /// a continuous stream of characters identifiable by unique text positions,
2395 /// and the actual memory layout of potentially discrete blocks of text in the
2396 /// client's backing store.
2397 ///
2398 /// If any of these callbacks returns an error, the analysis functions will
2399 /// stop prematurely and return a callback error. Rather than return E_NOTIMPL,
2400 /// an application should stub the method and return a constant/null and S_OK.
2401 /// </summary>
2402 interface DECLSPEC_UUID("688e1a58-5094-47c8-adc8-fbcea60ae92b") DECLSPEC_NOVTABLE IDWriteTextAnalysisSource : public IUnknown
2403 {
2404     /// <summary>
2405     /// Get a block of text starting at the specified text position.
2406     /// Returning NULL indicates the end of text - the position is after
2407     /// the last character. This function is called iteratively for
2408     /// each consecutive block, tying together several fragmented blocks
2409     /// in the backing store into a virtual contiguous string.
2410     /// </summary>
2411     /// <param name="textPosition">First position of the piece to obtain. All
2412     ///     positions are in UTF16 code-units, not whole characters, which
2413     ///     matters when supplementary characters are used.</param>
2414     /// <param name="textString">Address that receives a pointer to the text block
2415     ///     at the specified position.</param>
2416     /// <param name="textLength">Number of UTF16 units of the retrieved chunk.
2417     ///     The returned length is not the length of the block, but the length
2418     ///     remaining in the block, from the given position until its end.
2419     ///     So querying for a position that is 75 positions into a 100
2420     ///     postition block would return 25.</param>
2421     /// <returns>Pointer to the first character at the given text position.
2422     /// NULL indicates no chunk available at the specified position, either
2423     /// because textPosition >= the entire text content length or because the
2424     /// queried position is not mapped into the app's backing store.</returns>
2425     /// <remarks>
2426     /// Although apps can implement sparse textual content that only maps part of
2427     /// the backing store, the app must map any text that is in the range passed
2428     /// to any analysis functions.
2429     /// </remarks>
2430     STDMETHOD(GetTextAtPosition)(
2431         UINT32 textPosition,
2432         __out WCHAR const** textString,
2433         __out UINT32* textLength
2434         ) PURE;
2435 
2436     /// <summary>
2437     /// Get a block of text immediately preceding the specified position.
2438     /// </summary>
2439     /// <param name="textPosition">Position immediately after the last position of the chunk to obtain.</param>
2440     /// <param name="textString">Address that receives a pointer to the text block
2441     ///     at the specified position.</param>
2442     /// <param name="textLength">Number of UTF16 units of the retrieved block.
2443     ///     The length returned is from the given position to the front of
2444     ///     the block.</param>
2445     /// <returns>Pointer to the first character at (textPosition - textLength).
2446     /// NULL indicates no chunk available at the specified position, either
2447     /// because textPosition == 0,the textPosition > the entire text content
2448     /// length, or the queried position is not mapped into the app's backing
2449     /// store.</returns>
2450     /// <remarks>
2451     /// Although apps can implement sparse textual content that only maps part of
2452     /// the backing store, the app must map any text that is in the range passed
2453     /// to any analysis functions.
2454     /// </remarks>
2455     STDMETHOD(GetTextBeforePosition)(
2456         UINT32 textPosition,
2457         __out WCHAR const** textString,
2458         __out UINT32* textLength
2459         ) PURE;
2460 
2461     /// <summary>
2462     /// Get paragraph reading direction.
2463     /// </summary>
2464     STDMETHOD_(DWRITE_READING_DIRECTION, GetParagraphReadingDirection)() PURE;
2465 
2466     /// <summary>
2467     /// Get locale name on the range affected by it.
2468     /// </summary>
2469     /// <param name="textPosition">Position to get the locale name of.</param>
2470     /// <param name="textLength">Receives the length from the given position up to the
2471     ///     next differing locale.</param>
2472     /// <param name="localeName">Address that receives a pointer to the locale
2473     ///     at the specified position.</param>
2474     /// <remarks>
2475     /// The localeName pointer must remain valid until the next call or until
2476     /// the analysis returns.
2477     /// </remarks>
2478     STDMETHOD(GetLocaleName)(
2479         UINT32 textPosition,
2480         __out UINT32* textLength,
2481         __out_z WCHAR const** localeName
2482         ) PURE;
2483 
2484     /// <summary>
2485     /// Get number substitution on the range affected by it.
2486     /// </summary>
2487     /// <param name="textPosition">Position to get the number substitution of.</param>
2488     /// <param name="textLength">Receives the length from the given position up to the
2489     ///     next differing number substitution.</param>
2490     /// <param name="numberSubstitution">Address that receives a pointer to the number substitution
2491     ///     at the specified position.</param>
2492     /// <remarks>
2493     /// Any implementation should return the number substitution with an
2494     /// incremented ref count, and the analysis will release when finished
2495     /// with it (either before the next call or before it returns). However,
2496     /// the sink callback may hold onto it after that.
2497     /// </remarks>
2498     STDMETHOD(GetNumberSubstitution)(
2499         UINT32 textPosition,
2500         __out UINT32* textLength,
2501         __out IDWriteNumberSubstitution** numberSubstitution
2502         ) PURE;
2503 };
2504 
2505 /// <summary>
2506 /// The interface implemented by the text analyzer's client to receive the
2507 /// output of a given text analysis. The Text analyzer disregards any current
2508 /// state of the analysis sink, therefore a Set method call on a range
2509 /// overwrites the previously set analysis result of the same range.
2510 /// </summary>
2511 interface DECLSPEC_UUID("5810cd44-0ca0-4701-b3fa-bec5182ae4f6") DECLSPEC_NOVTABLE IDWriteTextAnalysisSink : public IUnknown
2512 {
2513     /// <summary>
2514     /// Report script analysis for the text range.
2515     /// </summary>
2516     /// <param name="textPosition">Starting position to report from.</param>
2517     /// <param name="textLength">Number of UTF16 units of the reported range.</param>
2518     /// <param name="scriptAnalysis">Script analysis of characters in range.</param>
2519     /// <returns>
2520     /// A successful code or error code to abort analysis.
2521     /// </returns>
2522     STDMETHOD(SetScriptAnalysis)(
2523         UINT32 textPosition,
2524         UINT32 textLength,
2525         __in DWRITE_SCRIPT_ANALYSIS const* scriptAnalysis
2526         ) PURE;
2527 
2528     /// <summary>
2529     /// Repport line-break opportunities for each character, starting from
2530     /// the specified position.
2531     /// </summary>
2532     /// <param name="textPosition">Starting position to report from.</param>
2533     /// <param name="textLength">Number of UTF16 units of the reported range.</param>
2534     /// <param name="lineBreakpoints">Breaking conditions for each character.</param>
2535     /// <returns>
2536     /// A successful code or error code to abort analysis.
2537     /// </returns>
2538     STDMETHOD(SetLineBreakpoints)(
2539         UINT32 textPosition,
2540         UINT32 textLength,
2541         __in_ecount(textLength) DWRITE_LINE_BREAKPOINT const* lineBreakpoints
2542         ) PURE;
2543 
2544     /// <summary>
2545     /// Set bidirectional level on the range, called once per each
2546     /// level run change (either explicit or resolved implicit).
2547     /// </summary>
2548     /// <param name="textPosition">Starting position to report from.</param>
2549     /// <param name="textLength">Number of UTF16 units of the reported range.</param>
2550     /// <param name="explicitLevel">Explicit level from embedded control codes
2551     ///     RLE/RLO/LRE/LRO/PDF, determined before any additional rules.</param>
2552     /// <param name="resolvedLevel">Final implicit level considering the
2553     ///     explicit level and characters' natural directionality, after all
2554     ///     Bidi rules have been applied.</param>
2555     /// <returns>
2556     /// A successful code or error code to abort analysis.
2557     /// </returns>
2558     STDMETHOD(SetBidiLevel)(
2559         UINT32 textPosition,
2560         UINT32 textLength,
2561         UINT8 explicitLevel,
2562         UINT8 resolvedLevel
2563         ) PURE;
2564 
2565     /// <summary>
2566     /// Set number substitution on the range.
2567     /// </summary>
2568     /// <param name="textPosition">Starting position to report from.</param>
2569     /// <param name="textLength">Number of UTF16 units of the reported range.</param>
2570     /// <param name="numberSubstitution">The number substitution applicable to
2571     ///     the returned range of text. The sink callback may hold onto it by
2572     ///     incrementing its ref count.</param>
2573     /// <returns>
2574     /// A successful code or error code to abort analysis.
2575     /// </returns>
2576     /// <remark>
2577     /// Unlike script and bidi analysis, where every character passed to the
2578     /// analyzer has a result, this will only be called for those ranges where
2579     /// substitution is applicable. For any other range, you will simply not
2580     /// be called.
2581     /// </remark>
2582     STDMETHOD(SetNumberSubstitution)(
2583         UINT32 textPosition,
2584         UINT32 textLength,
2585         __notnull IDWriteNumberSubstitution* numberSubstitution
2586         ) PURE;
2587 };
2588 
2589 /// <summary>
2590 /// Analyzes various text properties for complex script processing.
2591 /// </summary>
2592 interface DWRITE_DECLARE_INTERFACE("b7e6163e-7f46-43b4-84b3-e4e6249c365d") IDWriteTextAnalyzer : public IUnknown
2593 {
2594     /// <summary>
2595     /// Analyzes a text range for script boundaries, reading text attributes
2596     /// from the source and reporting the Unicode script ID to the sink
2597     /// callback SetScript.
2598     /// </summary>
2599     /// <param name="analysisSource">Source object to analyze.</param>
2600     /// <param name="textPosition">Starting position within the source object.</param>
2601     /// <param name="textLength">Length to analyze.</param>
2602     /// <param name="analysisSink">Callback object.</param>
2603     /// <returns>
2604     /// Standard HRESULT error code.
2605     /// </returns>
2606     STDMETHOD(AnalyzeScript)(
2607         IDWriteTextAnalysisSource* analysisSource,
2608         UINT32 textPosition,
2609         UINT32 textLength,
2610         IDWriteTextAnalysisSink* analysisSink
2611         ) PURE;
2612 
2613     /// <summary>
2614     /// Analyzes a text range for script directionality, reading attributes
2615     /// from the source and reporting levels to the sink callback SetBidiLevel.
2616     /// </summary>
2617     /// <param name="analysisSource">Source object to analyze.</param>
2618     /// <param name="textPosition">Starting position within the source object.</param>
2619     /// <param name="textLength">Length to analyze.</param>
2620     /// <param name="analysisSink">Callback object.</param>
2621     /// <returns>
2622     /// Standard HRESULT error code.
2623     /// </returns>
2624     /// <remarks>
2625     /// While the function can handle multiple paragraphs, the text range
2626     /// should not arbitrarily split the middle of paragraphs. Otherwise the
2627     /// returned levels may be wrong, since the Bidi algorithm is meant to
2628     /// apply to the paragraph as a whole.
2629     /// </remarks>
2630     /// <remarks>
2631     /// Embedded control codes (LRE/LRO/RLE/RLO/PDF) are taken into account.
2632     /// </remarks>
2633     STDMETHOD(AnalyzeBidi)(
2634         IDWriteTextAnalysisSource* analysisSource,
2635         UINT32 textPosition,
2636         UINT32 textLength,
2637         IDWriteTextAnalysisSink* analysisSink
2638         ) PURE;
2639 
2640     /// <summary>
2641     /// Analyzes a text range for spans where number substitution is applicable,
2642     /// reading attributes from the source and reporting substitutable ranges
2643     /// to the sink callback SetNumberSubstitution.
2644     /// </summary>
2645     /// <param name="analysisSource">Source object to analyze.</param>
2646     /// <param name="textPosition">Starting position within the source object.</param>
2647     /// <param name="textLength">Length to analyze.</param>
2648     /// <param name="analysisSink">Callback object.</param>
2649     /// <returns>
2650     /// Standard HRESULT error code.
2651     /// </returns>
2652     /// <remarks>
2653     /// While the function can handle multiple ranges of differing number
2654     /// substitutions, the text ranges should not arbitrarily split the
2655     /// middle of numbers. Otherwise it will treat the numbers separately
2656     /// and will not translate any intervening punctuation.
2657     /// </remarks>
2658     /// <remarks>
2659     /// Embedded control codes (LRE/LRO/RLE/RLO/PDF) are taken into account.
2660     /// </remarks>
2661     STDMETHOD(AnalyzeNumberSubstitution)(
2662         IDWriteTextAnalysisSource* analysisSource,
2663         UINT32 textPosition,
2664         UINT32 textLength,
2665         IDWriteTextAnalysisSink* analysisSink
2666         ) PURE;
2667 
2668     /// <summary>
2669     /// Analyzes a text range for potential breakpoint opportunities, reading
2670     /// attributes from the source and reporting breakpoint opportunities to
2671     /// the sink callback SetLineBreakpoints.
2672     /// </summary>
2673     /// <param name="analysisSource">Source object to analyze.</param>
2674     /// <param name="textPosition">Starting position within the source object.</param>
2675     /// <param name="textLength">Length to analyze.</param>
2676     /// <param name="analysisSink">Callback object.</param>
2677     /// <returns>
2678     /// Standard HRESULT error code.
2679     /// </returns>
2680     /// <remarks>
2681     /// While the function can handle multiple paragraphs, the text range
2682     /// should not arbitrarily split the middle of paragraphs, unless the
2683     /// given text span is considered a whole unit. Otherwise the
2684     /// returned properties for the first and last characters will
2685     /// inappropriately allow breaks.
2686     /// </remarks>
2687     /// <remarks>
2688     /// Special cases include the first, last, and surrogate characters. Any
2689     /// text span is treated as if adjacent to inline objects on either side.
2690     /// So the rules with contingent-break opportunities are used, where the
2691     /// edge between text and inline objects is always treated as a potential
2692     /// break opportunity, dependent on any overriding rules of the adjacent
2693     /// objects to prohibit or force the break (see Unicode TR #14).
2694     /// Surrogate pairs never break between.
2695     /// </remarks>
2696     STDMETHOD(AnalyzeLineBreakpoints)(
2697         IDWriteTextAnalysisSource* analysisSource,
2698         UINT32 textPosition,
2699         UINT32 textLength,
2700         IDWriteTextAnalysisSink* analysisSink
2701         ) PURE;
2702 
2703     /// <summary>
2704     /// Parses the input text string and maps it to the set of glyphs and associated glyph data
2705     /// according to the font and the writing system's rendering rules.
2706     /// </summary>
2707     /// <param name="textString">The string to convert to glyphs.</param>
2708     /// <param name="textLength">The length of textString.</param>
2709     /// <param name="fontFace">The font face to get glyphs from.</param>
2710     /// <param name="isSideways">Set to true if the text is intended to be
2711     /// drawn vertically.</param>
2712     /// <param name="isRightToLeft">Set to TRUE for right-to-left text.</param>
2713     /// <param name="scriptAnalysis">Script analysis result from AnalyzeScript.</param>
2714     /// <param name="localeName">The locale to use when selecting glyphs.
2715     /// e.g. the same character may map to different glyphs for ja-jp vs zh-chs.
2716     /// If this is NULL then the default mapping based on the script is used.</param>
2717     /// <param name="numberSubstitution">Optional number substitution which
2718     /// selects the appropriate glyphs for digits and related numeric characters,
2719     /// depending on the results obtained from AnalyzeNumberSubstitution. Passing
2720     /// null indicates that no substitution is needed and that the digits should
2721     /// receive nominal glyphs.</param>
2722     /// <param name="features">An array of pointers to the sets of typographic
2723     /// features to use in each feature range.</param>
2724     /// <param name="featureRangeLengths">The length of each feature range, in characters.
2725     /// The sum of all lengths should be equal to textLength.</param>
2726     /// <param name="featureRanges">The number of feature ranges.</param>
2727     /// <param name="maxGlyphCount">The maximum number of glyphs that can be
2728     /// returned.</param>
2729     /// <param name="clusterMap">The mapping from character ranges to glyph
2730     /// ranges.</param>
2731     /// <param name="textProps">Per-character output properties.</param>
2732     /// <param name="glyphIndices">Output glyph indices.</param>
2733     /// <param name="glyphProps">Per-glyph output properties.</param>
2734     /// <param name="actualGlyphCount">The actual number of glyphs returned if
2735     /// the call succeeds.</param>
2736     /// <returns>
2737     /// Standard HRESULT error code.
2738     /// </returns>
2739     /// <remarks>
2740     /// Note that the mapping from characters to glyphs is, in general, many-
2741     /// to-many.  The recommended estimate for the per-glyph output buffers is
2742     /// (3 * textLength / 2 + 16).  This is not guaranteed to be sufficient.
2743     ///
2744     /// The value of the actualGlyphCount parameter is only valid if the call
2745     /// succeeds.  In the event that maxGlyphCount is not big enough
2746     /// E_NOT_SUFFICIENT_BUFFER, which is equivalent to HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER),
2747     /// will be returned.  The application should allocate a larger buffer and try again.
2748     /// </remarks>
2749     STDMETHOD(GetGlyphs)(
2750         __in_ecount(textLength) WCHAR const* textString,
2751         UINT32 textLength,
2752         IDWriteFontFace* fontFace,
2753         BOOL isSideways,
2754         BOOL isRightToLeft,
2755         __in DWRITE_SCRIPT_ANALYSIS const* scriptAnalysis,
2756         __in_z_opt WCHAR const* localeName,
2757         __maybenull IDWriteNumberSubstitution* numberSubstitution,
2758         __in_ecount_opt(featureRanges) DWRITE_TYPOGRAPHIC_FEATURES const** features,
2759         __in_ecount_opt(featureRanges) UINT32 const* featureRangeLengths,
2760         UINT32 featureRanges,
2761         UINT32 maxGlyphCount,
2762         __out_ecount(textLength) UINT16* clusterMap,
2763         __out_ecount(textLength) DWRITE_SHAPING_TEXT_PROPERTIES* textProps,
2764         __out_ecount(maxGlyphCount) UINT16* glyphIndices,
2765         __out_ecount(maxGlyphCount) DWRITE_SHAPING_GLYPH_PROPERTIES* glyphProps,
2766         __out UINT32* actualGlyphCount
2767         ) PURE;
2768 
2769     /// <summary>
2770     /// Place glyphs output from the GetGlyphs method according to the font
2771     /// and the writing system's rendering rules.
2772     /// </summary>
2773     /// <param name="textString">The original string the glyphs came from.</param>
2774     /// <param name="clusterMap">The mapping from character ranges to glyph
2775     /// ranges. Returned by GetGlyphs.</param>
2776     /// <param name="textProps">Per-character properties. Returned by
2777     /// GetGlyphs.</param>
2778     /// <param name="textLength">The length of textString.</param>
2779     /// <param name="glyphIndices">Glyph indices. See GetGlyphs</param>
2780     /// <param name="glyphProps">Per-glyph properties. See GetGlyphs</param>
2781     /// <param name="glyphCount">The number of glyphs.</param>
2782     /// <param name="fontFace">The font face the glyphs came from.</param>
2783     /// <param name="fontEmSize">Logical font size in DIP's.</param>
2784     /// <param name="isSideways">Set to true if the text is intended to be
2785     /// drawn vertically.</param>
2786     /// <param name="isRightToLeft">Set to TRUE for right-to-left text.</param>
2787     /// <param name="scriptAnalysis">Script analysis result from AnalyzeScript.</param>
2788     /// <param name="localeName">The locale to use when selecting glyphs.
2789     /// e.g. the same character may map to different glyphs for ja-jp vs zh-chs.
2790     /// If this is NULL then the default mapping based on the script is used.</param>
2791     /// <param name="features">An array of pointers to the sets of typographic
2792     /// features to use in each feature range.</param>
2793     /// <param name="featureRangeLengths">The length of each feature range, in characters.
2794     /// The sum of all lengths should be equal to textLength.</param>
2795     /// <param name="featureRanges">The number of feature ranges.</param>
2796     /// <param name="glyphAdvances">The advance width of each glyph.</param>
2797     /// <param name="glyphOffsets">The offset of the origin of each glyph.</param>
2798     /// <returns>
2799     /// Standard HRESULT error code.
2800     /// </returns>
2801     STDMETHOD(GetGlyphPlacements)(
2802         __in_ecount(textLength) WCHAR const* textString,
2803         __in_ecount(textLength) UINT16 const* clusterMap,
2804         __in_ecount(textLength) DWRITE_SHAPING_TEXT_PROPERTIES* textProps,
2805         UINT32 textLength,
2806         __in_ecount(glyphCount) UINT16 const* glyphIndices,
2807         __in_ecount(glyphCount) DWRITE_SHAPING_GLYPH_PROPERTIES const* glyphProps,
2808         UINT32 glyphCount,
2809         IDWriteFontFace * fontFace,
2810         FLOAT fontEmSize,
2811         BOOL isSideways,
2812         BOOL isRightToLeft,
2813         __in DWRITE_SCRIPT_ANALYSIS const* scriptAnalysis,
2814         __in_z_opt WCHAR const* localeName,
2815         __in_ecount_opt(featureRanges) DWRITE_TYPOGRAPHIC_FEATURES const** features,
2816         __in_ecount_opt(featureRanges) UINT32 const* featureRangeLengths,
2817         UINT32 featureRanges,
2818         __out_ecount(glyphCount) FLOAT* glyphAdvances,
2819         __out_ecount(glyphCount) DWRITE_GLYPH_OFFSET* glyphOffsets
2820         ) PURE;
2821 
2822     /// <summary>
2823     /// Place glyphs output from the GetGlyphs method according to the font
2824     /// and the writing system's rendering rules.
2825     /// </summary>
2826     /// <param name="textString">The original string the glyphs came from.</param>
2827     /// <param name="clusterMap">The mapping from character ranges to glyph
2828     /// ranges. Returned by GetGlyphs.</param>
2829     /// <param name="textProps">Per-character properties. Returned by
2830     /// GetGlyphs.</param>
2831     /// <param name="textLength">The length of textString.</param>
2832     /// <param name="glyphIndices">Glyph indices. See GetGlyphs</param>
2833     /// <param name="glyphProps">Per-glyph properties. See GetGlyphs</param>
2834     /// <param name="glyphCount">The number of glyphs.</param>
2835     /// <param name="fontFace">The font face the glyphs came from.</param>
2836     /// <param name="fontEmSize">Logical font size in DIP's.</param>
2837     /// <param name="pixelsPerDip">Number of physical pixels per DIP. For example, if the DPI of the rendering surface is 96 this
2838     /// value is 1.0f. If the DPI is 120, this value is 120.0f/96.</param>
2839     /// <param name="transform">Optional transform applied to the glyphs and their positions. This transform is applied after the
2840     /// scaling specified by the font size and pixelsPerDip.</param>
2841     /// <param name="useGdiNatural">
2842     /// When set to FALSE, the metrics are the same as the metrics of GDI aliased text.
2843     /// When set to TRUE, the metrics are the same as the metrics of text measured by GDI using a font
2844     /// created with CLEARTYPE_NATURAL_QUALITY.
2845     /// </param>
2846     /// <param name="isSideways">Set to true if the text is intended to be
2847     /// drawn vertically.</param>
2848     /// <param name="isRightToLeft">Set to TRUE for right-to-left text.</param>
2849     /// <param name="scriptAnalysis">Script analysis result from AnalyzeScript.</param>
2850     /// <param name="localeName">The locale to use when selecting glyphs.
2851     /// e.g. the same character may map to different glyphs for ja-jp vs zh-chs.
2852     /// If this is NULL then the default mapping based on the script is used.</param>
2853     /// <param name="features">An array of pointers to the sets of typographic
2854     /// features to use in each feature range.</param>
2855     /// <param name="featureRangeLengths">The length of each feature range, in characters.
2856     /// The sum of all lengths should be equal to textLength.</param>
2857     /// <param name="featureRanges">The number of feature ranges.</param>
2858     /// <param name="glyphAdvances">The advance width of each glyph.</param>
2859     /// <param name="glyphOffsets">The offset of the origin of each glyph.</param>
2860     /// <returns>
2861     /// Standard HRESULT error code.
2862     /// </returns>
2863     STDMETHOD(GetGdiCompatibleGlyphPlacements)(
2864         __in_ecount(textLength) WCHAR const* textString,
2865         __in_ecount(textLength) UINT16 const* clusterMap,
2866         __in_ecount(textLength) DWRITE_SHAPING_TEXT_PROPERTIES* textProps,
2867         UINT32 textLength,
2868         __in_ecount(glyphCount) UINT16 const* glyphIndices,
2869         __in_ecount(glyphCount) DWRITE_SHAPING_GLYPH_PROPERTIES const* glyphProps,
2870         UINT32 glyphCount,
2871         IDWriteFontFace * fontFace,
2872         FLOAT fontEmSize,
2873         FLOAT pixelsPerDip,
2874         __in_opt DWRITE_MATRIX const* transform,
2875         BOOL useGdiNatural,
2876         BOOL isSideways,
2877         BOOL isRightToLeft,
2878         __in DWRITE_SCRIPT_ANALYSIS const* scriptAnalysis,
2879         __in_z_opt WCHAR const* localeName,
2880         __in_ecount_opt(featureRanges) DWRITE_TYPOGRAPHIC_FEATURES const** features,
2881         __in_ecount_opt(featureRanges) UINT32 const* featureRangeLengths,
2882         UINT32 featureRanges,
2883         __out_ecount(glyphCount) FLOAT* glyphAdvances,
2884         __out_ecount(glyphCount) DWRITE_GLYPH_OFFSET* glyphOffsets
2885         ) PURE;
2886 };
2887 
2888 /// <summary>
2889 /// The DWRITE_GLYPH_RUN structure contains the information needed by renderers
2890 /// to draw glyph runs. All coordinates are in device independent pixels (DIPs).
2891 /// </summary>
2892 struct DWRITE_GLYPH_RUN
2893 {
2894     /// <summary>
2895     /// The physical font face to draw with.
2896     /// </summary>
2897     __notnull IDWriteFontFace* fontFace;
2898 
2899     /// <summary>
2900     /// Logical size of the font in DIPs, not points (equals 1/96 inch).
2901     /// </summary>
2902     FLOAT fontEmSize;
2903 
2904     /// <summary>
2905     /// The number of glyphs.
2906     /// </summary>
2907     UINT32 glyphCount;
2908 
2909     /// <summary>
2910     /// The indices to render.
2911     /// </summary>
2912     __field_ecount(glyphCount) UINT16 const* glyphIndices;
2913 
2914     /// <summary>
2915     /// Glyph advance widths.
2916     /// </summary>
2917     __field_ecount_opt(glyphCount) FLOAT const* glyphAdvances;
2918 
2919     /// <summary>
2920     /// Glyph offsets.
2921     /// </summary>
2922     __field_ecount_opt(glyphCount) DWRITE_GLYPH_OFFSET const* glyphOffsets;
2923 
2924     /// <summary>
2925     /// If true, specifies that glyphs are rotated 90 degrees to the left and
2926     /// vertical metrics are used. Vertical writing is achieved by specifying
2927     /// isSideways = true and rotating the entire run 90 degrees to the right
2928     /// via a rotate transform.
2929     /// </summary>
2930     BOOL isSideways;
2931 
2932     /// <summary>
2933     /// The implicit resolved bidi level of the run. Odd levels indicate
2934     /// right-to-left languages like Hebrew and Arabic, while even levels
2935     /// indicate left-to-right languages like English and Japanese (when
2936     /// written horizontally). For right-to-left languages, the text origin
2937     /// is on the right, and text should be drawn to the left.
2938     /// </summary>
2939     UINT32 bidiLevel;
2940 };
2941 
2942 /// <summary>
2943 /// The DWRITE_GLYPH_RUN_DESCRIPTION structure contains additional properties
2944 /// related to those in DWRITE_GLYPH_RUN.
2945 /// </summary>
2946 struct DWRITE_GLYPH_RUN_DESCRIPTION
2947 {
2948     /// <summary>
2949     /// The locale name associated with this run.
2950     /// </summary>
2951     __nullterminated WCHAR const* localeName;
2952 
2953     /// <summary>
2954     /// The text associated with the glyphs.
2955     /// </summary>
2956     __field_ecount(stringLength) WCHAR const* string;
2957 
2958     /// <summary>
2959     /// The number of characters (UTF16 code-units).
2960     /// Note that this may be different than the number of glyphs.
2961     /// </summary>
2962     UINT32 stringLength;
2963 
2964     /// <summary>
2965     /// An array of indices to the glyph indices array, of the first glyphs of
2966     /// all the glyph clusters of the glyphs to render.
2967     /// </summary>
2968     __field_ecount(stringLength) UINT16 const* clusterMap;
2969 
2970     /// <summary>
2971     /// Corresponding text position in the original string
2972     /// this glyph run came from.
2973     /// </summary>
2974     UINT32 textPosition;
2975 };
2976 
2977 /// <summary>
2978 /// The DWRITE_UNDERLINE structure contains about the size and placement of
2979 /// underlines. All coordinates are in device independent pixels (DIPs).
2980 /// </summary>
2981 struct DWRITE_UNDERLINE
2982 {
2983     /// <summary>
2984     /// Width of the underline, measured parallel to the baseline.
2985     /// </summary>
2986     FLOAT width;
2987 
2988     /// <summary>
2989     /// Thickness of the underline, measured perpendicular to the
2990     /// baseline.
2991     /// </summary>
2992     FLOAT thickness;
2993 
2994     /// <summary>
2995     /// Offset of the underline from the baseline.
2996     /// A positive offset represents a position below the baseline and
2997     /// a negative offset is above.
2998     /// </summary>
2999     FLOAT offset;
3000 
3001     /// <summary>
3002     /// Height of the tallest run where the underline applies.
3003     /// </summary>
3004     FLOAT runHeight;
3005 
3006     /// <summary>
3007     /// Reading direction of the text associated with the underline.  This
3008     /// value is used to interpret whether the width value runs horizontally
3009     /// or vertically.
3010     /// </summary>
3011     DWRITE_READING_DIRECTION readingDirection;
3012 
3013     /// <summary>
3014     /// Flow direction of the text associated with the underline.  This value
3015     /// is used to interpret whether the thickness value advances top to
3016     /// bottom, left to right, or right to left.
3017     /// </summary>
3018     DWRITE_FLOW_DIRECTION flowDirection;
3019 
3020     /// <summary>
3021     /// Locale of the text the underline is being drawn under. Can be
3022     /// pertinent where the locale affects how the underline is drawn.
3023     /// For example, in vertical text, the underline belongs on the
3024     /// left for Chinese but on the right for Japanese.
3025     /// This choice is completely left up to higher levels.
3026     /// </summary>
3027     __nullterminated WCHAR const* localeName;
3028 
3029     /// <summary>
3030     /// The measuring mode can be useful to the renderer to determine how
3031     /// underlines are rendered, e.g. rounding the thickness to a whole pixel
3032     /// in GDI-compatible modes.
3033     /// </summary>
3034     DWRITE_MEASURING_MODE measuringMode;
3035 };
3036 
3037 /// <summary>
3038 /// The DWRITE_STRIKETHROUGH structure contains about the size and placement of
3039 /// strickthroughs. All coordinates are in device independent pixels (DIPs).
3040 /// </summary>
3041 struct DWRITE_STRIKETHROUGH
3042 {
3043     /// <summary>
3044     /// Width of the strikethrough, measured parallel to the baseline.
3045     /// </summary>
3046     FLOAT width;
3047 
3048     /// <summary>
3049     /// Thickness of the strikethrough, measured perpendicular to the
3050     /// baseline.
3051     /// </summary>
3052     FLOAT thickness;
3053 
3054     /// <summary>
3055     /// Offset of the stikethrough from the baseline.
3056     /// A positive offset represents a position below the baseline and
3057     /// a negative offset is above.
3058     /// </summary>
3059     FLOAT offset;
3060 
3061     /// <summary>
3062     /// Reading direction of the text associated with the strikethrough.  This
3063     /// value is used to interpret whether the width value runs horizontally
3064     /// or vertically.
3065     /// </summary>
3066     DWRITE_READING_DIRECTION readingDirection;
3067 
3068     /// <summary>
3069     /// Flow direction of the text associated with the strikethrough.  This
3070     /// value is used to interpret whether the thickness value advances top to
3071     /// bottom, left to right, or right to left.
3072     /// </summary>
3073     DWRITE_FLOW_DIRECTION flowDirection;
3074 
3075     /// <summary>
3076     /// Locale of the range. Can be pertinent where the locale affects the style.
3077     /// </summary>
3078     __nullterminated WCHAR const* localeName;
3079 
3080     /// <summary>
3081     /// The measuring mode can be useful to the renderer to determine how
3082     /// underlines are rendered, e.g. rounding the thickness to a whole pixel
3083     /// in GDI-compatible modes.
3084     /// </summary>
3085     DWRITE_MEASURING_MODE measuringMode;
3086 };
3087 
3088 /// <summary>
3089 /// The DWRITE_LINE_METRICS structure contains information about a formatted
3090 /// line of text.
3091 /// </summary>
3092 struct DWRITE_LINE_METRICS
3093 {
3094     /// <summary>
3095     /// The number of total text positions in the line.
3096     /// This includes any trailing whitespace and newline characters.
3097     /// </summary>
3098     UINT32 length;
3099 
3100     /// <summary>
3101     /// The number of whitespace positions at the end of the line.  Newline
3102     /// sequences are considered whitespace.
3103     /// </summary>
3104     UINT32 trailingWhitespaceLength;
3105 
3106     /// <summary>
3107     /// The number of characters in the newline sequence at the end of the line.
3108     /// If the count is zero, then the line was either wrapped or it is the
3109     /// end of the text.
3110     /// </summary>
3111     UINT32 newlineLength;
3112 
3113     /// <summary>
3114     /// Height of the line as measured from top to bottom.
3115     /// </summary>
3116     FLOAT height;
3117 
3118     /// <summary>
3119     /// Distance from the top of the line to its baseline.
3120     /// </summary>
3121     FLOAT baseline;
3122 
3123     /// <summary>
3124     /// The line is trimmed.
3125     /// </summary>
3126     BOOL isTrimmed;
3127 };
3128 
3129 
3130 /// <summary>
3131 /// The DWRITE_CLUSTER_METRICS structure contains information about a glyph cluster.
3132 /// </summary>
3133 struct DWRITE_CLUSTER_METRICS
3134 {
3135     /// <summary>
3136     /// The total advance width of all glyphs in the cluster.
3137     /// </summary>
3138     FLOAT width;
3139 
3140     /// <summary>
3141     /// The number of text positions in the cluster.
3142     /// </summary>
3143     UINT16 length;
3144 
3145     /// <summary>
3146     /// Indicate whether line can be broken right after the cluster.
3147     /// </summary>
3148     UINT16 canWrapLineAfter : 1;
3149 
3150     /// <summary>
3151     /// Indicate whether the cluster corresponds to whitespace character.
3152     /// </summary>
3153     UINT16 isWhitespace : 1;
3154 
3155     /// <summary>
3156     /// Indicate whether the cluster corresponds to a newline character.
3157     /// </summary>
3158     UINT16 isNewline : 1;
3159 
3160     /// <summary>
3161     /// Indicate whether the cluster corresponds to soft hyphen character.
3162     /// </summary>
3163     UINT16 isSoftHyphen : 1;
3164 
3165     /// <summary>
3166     /// Indicate whether the cluster is read from right to left.
3167     /// </summary>
3168     UINT16 isRightToLeft : 1;
3169 
3170     UINT16 padding : 11;
3171 };
3172 
3173 
3174 /// <summary>
3175 /// Overall metrics associated with text after layout.
3176 /// All coordinates are in device independent pixels (DIPs).
3177 /// </summary>
3178 struct DWRITE_TEXT_METRICS
3179 {
3180     /// <summary>
3181     /// Left-most point of formatted text relative to layout box
3182     /// (excluding any glyph overhang).
3183     /// </summary>
3184     FLOAT left;
3185 
3186     /// <summary>
3187     /// Top-most point of formatted text relative to layout box
3188     /// (excluding any glyph overhang).
3189     /// </summary>
3190     FLOAT top;
3191 
3192     /// <summary>
3193     /// The width of the formatted text ignoring trailing whitespace
3194     /// at the end of each line.
3195     /// </summary>
3196     FLOAT width;
3197 
3198     /// <summary>
3199     /// The width of the formatted text taking into account the
3200     /// trailing whitespace at the end of each line.
3201     /// </summary>
3202     FLOAT widthIncludingTrailingWhitespace;
3203 
3204     /// <summary>
3205     /// The height of the formatted text. The height of an empty string
3206     /// is determined by the size of the default font's line height.
3207     /// </summary>
3208     FLOAT height;
3209 
3210     /// <summary>
3211     /// Initial width given to the layout. Depending on whether the text
3212     /// was wrapped or not, it can be either larger or smaller than the
3213     /// text content width.
3214     /// </summary>
3215     FLOAT layoutWidth;
3216 
3217     /// <summary>
3218     /// Initial height given to the layout. Depending on the length of the
3219     /// text, it may be larger or smaller than the text content height.
3220     /// </summary>
3221     FLOAT layoutHeight;
3222 
3223     /// <summary>
3224     /// The maximum reordering count of any line of text, used
3225     /// to calculate the most number of hit-testing boxes needed.
3226     /// If the layout has no bidirectional text or no text at all,
3227     /// the minimum level is 1.
3228     /// </summary>
3229     UINT32 maxBidiReorderingDepth;
3230 
3231     /// <summary>
3232     /// Total number of lines.
3233     /// </summary>
3234     UINT32 lineCount;
3235 };
3236 
3237 
3238 /// <summary>
3239 /// Properties describing the geometric measurement of an
3240 /// application-defined inline object.
3241 /// </summary>
3242 struct DWRITE_INLINE_OBJECT_METRICS
3243 {
3244     /// <summary>
3245     /// Width of the inline object.
3246     /// </summary>
3247     FLOAT width;
3248 
3249     /// <summary>
3250     /// Height of the inline object as measured from top to bottom.
3251     /// </summary>
3252     FLOAT height;
3253 
3254     /// <summary>
3255     /// Distance from the top of the object to the baseline where it is lined up with the adjacent text.
3256     /// If the baseline is at the bottom, baseline simply equals height.
3257     /// </summary>
3258     FLOAT baseline;
3259 
3260     /// <summary>
3261     /// Flag indicating whether the object is to be placed upright or alongside the text baseline
3262     /// for vertical text.
3263     /// </summary>
3264     BOOL  supportsSideways;
3265 };
3266 
3267 
3268 /// <summary>
3269 /// The DWRITE_OVERHANG_METRICS structure holds how much any visible pixels
3270 /// (in DIPs) overshoot each side of the layout or inline objects.
3271 /// </summary>
3272 /// <remarks>
3273 /// Positive overhangs indicate that the visible area extends outside the layout
3274 /// box or inline object, while negative values mean there is whitespace inside.
3275 /// The returned values are unaffected by rendering transforms or pixel snapping.
3276 /// Additionally, they may not exactly match final target's pixel bounds after
3277 /// applying grid fitting and hinting.
3278 /// </remarks>
3279 struct DWRITE_OVERHANG_METRICS
3280 {
3281     /// <summary>
3282     /// The distance from the left-most visible DIP to its left alignment edge.
3283     /// </summary>
3284     FLOAT left;
3285 
3286     /// <summary>
3287     /// The distance from the top-most visible DIP to its top alignment edge.
3288     /// </summary>
3289     FLOAT top;
3290 
3291     /// <summary>
3292     /// The distance from the right-most visible DIP to its right alignment edge.
3293     /// </summary>
3294     FLOAT right;
3295 
3296     /// <summary>
3297     /// The distance from the bottom-most visible DIP to its bottom alignment edge.
3298     /// </summary>
3299     FLOAT bottom;
3300 };
3301 
3302 
3303 /// <summary>
3304 /// Geometry enclosing of text positions.
3305 /// </summary>
3306 struct DWRITE_HIT_TEST_METRICS
3307 {
3308     /// <summary>
3309     /// First text position within the geometry.
3310     /// </summary>
3311     UINT32 textPosition;
3312 
3313     /// <summary>
3314     /// Number of text positions within the geometry.
3315     /// </summary>
3316     UINT32 length;
3317 
3318     /// <summary>
3319     /// Left position of the top-left coordinate of the geometry.
3320     /// </summary>
3321     FLOAT left;
3322 
3323     /// <summary>
3324     /// Top position of the top-left coordinate of the geometry.
3325     /// </summary>
3326     FLOAT top;
3327 
3328     /// <summary>
3329     /// Geometry's width.
3330     /// </summary>
3331     FLOAT width;
3332 
3333     /// <summary>
3334     /// Geometry's height.
3335     /// </summary>
3336     FLOAT height;
3337 
3338     /// <summary>
3339     /// Bidi level of text positions enclosed within the geometry.
3340     /// </summary>
3341     UINT32 bidiLevel;
3342 
3343     /// <summary>
3344     /// Geometry encloses text?
3345     /// </summary>
3346     BOOL isText;
3347 
3348     /// <summary>
3349     /// Range is trimmed.
3350     /// </summary>
3351     BOOL isTrimmed;
3352 };
3353 
3354 
3355 interface IDWriteTextRenderer;
3356 
3357 
3358 /// <summary>
3359 /// The IDWriteInlineObject interface wraps an application defined inline graphic,
3360 /// allowing DWrite to query metrics as if it was a glyph inline with the text.
3361 /// </summary>
3362 interface DWRITE_DECLARE_INTERFACE("8339FDE3-106F-47ab-8373-1C6295EB10B3") IDWriteInlineObject : public IUnknown
3363 {
3364     /// <summary>
3365     /// The application implemented rendering callback (IDWriteTextRenderer::DrawInlineObject)
3366     /// can use this to draw the inline object without needing to cast or query the object
3367     /// type. The text layout does not call this method directly.
3368     /// </summary>
3369     /// <param name="clientDrawingContext">The context passed to IDWriteTextLayout::Draw.</param>
3370     /// <param name="renderer">The renderer passed to IDWriteTextLayout::Draw as the object's containing parent.</param>
3371     /// <param name="originX">X-coordinate at the top-left corner of the inline object.</param>
3372     /// <param name="originY">Y-coordinate at the top-left corner of the inline object.</param>
3373     /// <param name="isSideways">The object should be drawn on its side.</param>
3374     /// <param name="isRightToLeft">The object is in an right-to-left context and should be drawn flipped.</param>
3375     /// <param name="clientDrawingEffect">The drawing effect set in IDWriteTextLayout::SetDrawingEffect.</param>
3376     /// <returns>
3377     /// Standard HRESULT error code.
3378     /// </returns>
3379     STDMETHOD(Draw)(
3380         __maybenull void* clientDrawingContext,
3381         IDWriteTextRenderer* renderer,
3382         FLOAT originX,
3383         FLOAT originY,
3384         BOOL isSideways,
3385         BOOL isRightToLeft,
3386         __maybenull IUnknown* clientDrawingEffect
3387         ) PURE;
3388 
3389     /// <summary>
3390     /// TextLayout calls this callback function to get the measurement of the inline object.
3391     /// </summary>
3392     /// <param name="metrics">Returned metrics</param>
3393     /// <returns>
3394     /// Standard HRESULT error code.
3395     /// </returns>
3396     STDMETHOD(GetMetrics)(
3397         __out DWRITE_INLINE_OBJECT_METRICS* metrics
3398         ) PURE;
3399 
3400     /// <summary>
3401     /// TextLayout calls this callback function to get the visible extents (in DIPs) of the inline object.
3402     /// In the case of a simple bitmap, with no padding and no overhang, all the overhangs will
3403     /// simply be zeroes.
3404     /// </summary>
3405     /// <param name="overhangs">Overshoot of visible extents (in DIPs) outside the object.</param>
3406     /// <returns>
3407     /// Standard HRESULT error code.
3408     /// </returns>
3409     /// <remarks>
3410     /// The overhangs should be returned relative to the reported size of the object
3411     /// (DWRITE_INLINE_OBJECT_METRICS::width/height), and should not be baseline
3412     /// adjusted. If you have an image that is actually 100x100 DIPs, but you want it
3413     /// slightly inset (perhaps it has a glow) by 20 DIPs on each side, you would
3414     /// return a width/height of 60x60 and four overhangs of 20 DIPs.
3415     /// </remarks>
3416     STDMETHOD(GetOverhangMetrics)(
3417         __out DWRITE_OVERHANG_METRICS* overhangs
3418         ) PURE;
3419 
3420     /// <summary>
3421     /// Layout uses this to determine the line breaking behavior of the inline object
3422     /// amidst the text.
3423     /// </summary>
3424     /// <param name="breakConditionBefore">Line-breaking condition between the object and the content immediately preceding it.</param>
3425     /// <param name="breakConditionAfter" >Line-breaking condition between the object and the content immediately following it.</param>
3426     /// <returns>
3427     /// Standard HRESULT error code.
3428     /// </returns>
3429     STDMETHOD(GetBreakConditions)(
3430         __out DWRITE_BREAK_CONDITION* breakConditionBefore,
3431         __out DWRITE_BREAK_CONDITION* breakConditionAfter
3432         ) PURE;
3433 };
3434 
3435 /// <summary>
3436 /// The IDWritePixelSnapping interface defines the pixel snapping properties of a text renderer.
3437 /// </summary>
3438 interface DWRITE_DECLARE_INTERFACE("eaf3a2da-ecf4-4d24-b644-b34f6842024b") IDWritePixelSnapping : public IUnknown
3439 {
3440     /// <summary>
3441     /// Determines whether pixel snapping is disabled. The recommended default is FALSE,
3442     /// unless doing animation that requires subpixel vertical placement.
3443     /// </summary>
3444     /// <param name="clientDrawingContext">The context passed to IDWriteTextLayout::Draw.</param>
3445     /// <param name="isDisabled">Receives TRUE if pixel snapping is disabled or FALSE if it not.</param>
3446     /// <returns>
3447     /// Standard HRESULT error code.
3448     /// </returns>
3449     STDMETHOD(IsPixelSnappingDisabled)(
3450         __maybenull void* clientDrawingContext,
3451         __out BOOL* isDisabled
3452         ) PURE;
3453 
3454     /// <summary>
3455     /// Gets the current transform that maps abstract coordinates to DIPs,
3456     /// which may disable pixel snapping upon any rotation or shear.
3457     /// </summary>
3458     /// <param name="clientDrawingContext">The context passed to IDWriteTextLayout::Draw.</param>
3459     /// <param name="transform">Receives the transform.</param>
3460     /// <returns>
3461     /// Standard HRESULT error code.
3462     /// </returns>
3463     STDMETHOD(GetCurrentTransform)(
3464         __maybenull void* clientDrawingContext,
3465         __out DWRITE_MATRIX* transform
3466         ) PURE;
3467 
3468     /// <summary>
3469     /// Gets the number of physical pixels per DIP. A DIP (device-independent pixel) is 1/96 inch,
3470     /// so the pixelsPerDip value is the number of logical pixels per inch divided by 96 (yielding
3471     /// a value of 1 for 96 DPI and 1.25 for 120).
3472     /// </summary>
3473     /// <param name="clientDrawingContext">The context passed to IDWriteTextLayout::Draw.</param>
3474     /// <param name="pixelsPerDip">Receives the number of physical pixels per DIP.</param>
3475     /// <returns>
3476     /// Standard HRESULT error code.
3477     /// </returns>
3478     STDMETHOD(GetPixelsPerDip)(
3479         __maybenull void* clientDrawingContext,
3480         __out FLOAT* pixelsPerDip
3481         ) PURE;
3482 };
3483 
3484 /// <summary>
3485 /// The IDWriteTextLayout interface represents a set of application-defined
3486 /// callbacks that perform rendering of text, inline objects, and decorations
3487 /// such as underlines.
3488 /// </summary>
3489 interface DWRITE_DECLARE_INTERFACE("ef8a8135-5cc6-45fe-8825-c5a0724eb819") IDWriteTextRenderer : public IDWritePixelSnapping
3490 {
3491     /// <summary>
3492     /// IDWriteTextLayout::Draw calls this function to instruct the client to
3493     /// render a run of glyphs.
3494     /// </summary>
3495     /// <param name="clientDrawingContext">The context passed to
3496     /// IDWriteTextLayout::Draw.</param>
3497     /// <param name="baselineOriginX">X-coordinate of the baseline.</param>
3498     /// <param name="baselineOriginY">Y-coordinate of the baseline.</param>
3499     /// <param name="measuringMode">Specifies measuring method for glyphs in the run.
3500     /// Renderer implementations may choose different rendering modes for given measuring methods,
3501     /// but best results are seen when the rendering mode matches the corresponding measuring mode:
3502     /// DWRITE_RENDERING_MODE_CLEARTYPE_NATURAL for DWRITE_MEASURING_MODE_NATURAL
3503     /// DWRITE_RENDERING_MODE_CLEARTYPE_GDI_CLASSIC for DWRITE_MEASURING_MODE_GDI_CLASSIC
3504     /// DWRITE_RENDERING_MODE_CLEARTYPE_GDI_NATURAL for DWRITE_MEASURING_MODE_GDI_NATURAL
3505     /// </param>
3506     /// <param name="glyphRun">The glyph run to draw.</param>
3507     /// <param name="glyphRunDescription">Properties of the characters
3508     /// associated with this run.</param>
3509     /// <param name="clientDrawingEffect">The drawing effect set in
3510     /// IDWriteTextLayout::SetDrawingEffect.</param>
3511     /// <returns>
3512     /// Standard HRESULT error code.
3513     /// </returns>
3514     STDMETHOD(DrawGlyphRun)(
3515         __maybenull void* clientDrawingContext,
3516         FLOAT baselineOriginX,
3517         FLOAT baselineOriginY,
3518         DWRITE_MEASURING_MODE measuringMode,
3519         __in DWRITE_GLYPH_RUN const* glyphRun,
3520         __in DWRITE_GLYPH_RUN_DESCRIPTION const* glyphRunDescription,
3521         __maybenull IUnknown* clientDrawingEffect
3522         ) PURE;
3523 
3524     /// <summary>
3525     /// IDWriteTextLayout::Draw calls this function to instruct the client to draw
3526     /// an underline.
3527     /// </summary>
3528     /// <param name="clientDrawingContext">The context passed to
3529     /// IDWriteTextLayout::Draw.</param>
3530     /// <param name="baselineOriginX">X-coordinate of the baseline.</param>
3531     /// <param name="baselineOriginY">Y-coordinate of the baseline.</param>
3532     /// <param name="underline">Underline logical information.</param>
3533     /// <param name="clientDrawingEffect">The drawing effect set in
3534     /// IDWriteTextLayout::SetDrawingEffect.</param>
3535     /// <returns>
3536     /// Standard HRESULT error code.
3537     /// </returns>
3538     /// <remarks>
3539     /// A single underline can be broken into multiple calls, depending on
3540     /// how the formatting changes attributes. If font sizes/styles change
3541     /// within an underline, the thickness and offset will be averaged
3542     /// weighted according to characters.
3543     /// To get the correct top coordinate of the underline rect, add underline::offset
3544     /// to the baseline's Y. Otherwise the underline will be immediately under the text.
3545     /// The x coordinate will always be passed as the left side, regardless
3546     /// of text directionality. This simplifies drawing and reduces the
3547     /// problem of round-off that could potentially cause gaps or a double
3548     /// stamped alpha blend. To avoid alpha overlap, round the end points
3549     /// to the nearest device pixel.
3550     /// </remarks>
3551     STDMETHOD(DrawUnderline)(
3552         __maybenull void* clientDrawingContext,
3553         FLOAT baselineOriginX,
3554         FLOAT baselineOriginY,
3555         __in DWRITE_UNDERLINE const* underline,
3556         __maybenull IUnknown* clientDrawingEffect
3557         ) PURE;
3558 
3559     /// <summary>
3560     /// IDWriteTextLayout::Draw calls this function to instruct the client to draw
3561     /// a strikethrough.
3562     /// </summary>
3563     /// <param name="clientDrawingContext">The context passed to
3564     /// IDWriteTextLayout::Draw.</param>
3565     /// <param name="baselineOriginX">X-coordinate of the baseline.</param>
3566     /// <param name="baselineOriginY">Y-coordinate of the baseline.</param>
3567     /// <param name="strikethrough">Strikethrough logical information.</param>
3568     /// <param name="clientDrawingEffect">The drawing effect set in
3569     /// IDWriteTextLayout::SetDrawingEffect.</param>
3570     /// <returns>
3571     /// Standard HRESULT error code.
3572     /// </returns>
3573     /// <remarks>
3574     /// A single strikethrough can be broken into multiple calls, depending on
3575     /// how the formatting changes attributes. Strikethrough is not averaged
3576     /// across font sizes/styles changes.
3577     /// To get the correct top coordinate of the strikethrough rect,
3578     /// add strikethrough::offset to the baseline's Y.
3579     /// Like underlines, the x coordinate will always be passed as the left side,
3580     /// regardless of text directionality.
3581     /// </remarks>
3582     STDMETHOD(DrawStrikethrough)(
3583         __maybenull void* clientDrawingContext,
3584         FLOAT baselineOriginX,
3585         FLOAT baselineOriginY,
3586         __in DWRITE_STRIKETHROUGH const* strikethrough,
3587         __maybenull IUnknown* clientDrawingEffect
3588         ) PURE;
3589 
3590     /// <summary>
3591     /// IDWriteTextLayout::Draw calls this application callback when it needs to
3592     /// draw an inline object.
3593     /// </summary>
3594     /// <param name="clientDrawingContext">The context passed to IDWriteTextLayout::Draw.</param>
3595     /// <param name="originX">X-coordinate at the top-left corner of the inline object.</param>
3596     /// <param name="originY">Y-coordinate at the top-left corner of the inline object.</param>
3597     /// <param name="inlineObject">The object set using IDWriteTextLayout::SetInlineObject.</param>
3598     /// <param name="isSideways">The object should be drawn on its side.</param>
3599     /// <param name="isRightToLeft">The object is in an right-to-left context and should be drawn flipped.</param>
3600     /// <param name="clientDrawingEffect">The drawing effect set in
3601     /// IDWriteTextLayout::SetDrawingEffect.</param>
3602     /// <returns>
3603     /// Standard HRESULT error code.
3604     /// </returns>
3605     /// <remarks>
3606     /// The right-to-left flag is a hint for those cases where it would look
3607     /// strange for the image to be shown normally (like an arrow pointing to
3608     /// right to indicate a submenu).
3609     /// </remarks>
3610     STDMETHOD(DrawInlineObject)(
3611         __maybenull void* clientDrawingContext,
3612         FLOAT originX,
3613         FLOAT originY,
3614         IDWriteInlineObject* inlineObject,
3615         BOOL isSideways,
3616         BOOL isRightToLeft,
3617         __maybenull IUnknown* clientDrawingEffect
3618         ) PURE;
3619 };
3620 
3621 /// <summary>
3622 /// The IDWriteTextLayout interface represents a block of text after it has
3623 /// been fully analyzed and formatted.
3624 ///
3625 /// All coordinates are in device independent pixels (DIPs).
3626 /// </summary>
3627 interface DWRITE_DECLARE_INTERFACE("53737037-6d14-410b-9bfe-0b182bb70961") IDWriteTextLayout : public IDWriteTextFormat
3628 {
3629     /// <summary>
3630     /// Set layout maximum width
3631     /// </summary>
3632     /// <param name="maxWidth">Layout maximum width</param>
3633     /// <returns>
3634     /// Standard HRESULT error code.
3635     /// </returns>
3636     STDMETHOD(SetMaxWidth)(
3637         FLOAT maxWidth
3638         ) PURE;
3639 
3640     /// <summary>
3641     /// Set layout maximum height
3642     /// </summary>
3643     /// <param name="maxHeight">Layout maximum height</param>
3644     /// <returns>
3645     /// Standard HRESULT error code.
3646     /// </returns>
3647     STDMETHOD(SetMaxHeight)(
3648         FLOAT maxHeight
3649         ) PURE;
3650 
3651     /// <summary>
3652     /// Set the font collection.
3653     /// </summary>
3654     /// <param name="fontCollection">The font collection to set</param>
3655     /// <param name="textRange">Text range to which this change applies.</param>
3656     /// <returns>
3657     /// Standard HRESULT error code.
3658     /// </returns>
3659     STDMETHOD(SetFontCollection)(
3660         IDWriteFontCollection* fontCollection,
3661         DWRITE_TEXT_RANGE textRange
3662         ) PURE;
3663 
3664     /// <summary>
3665     /// Set null-terminated font family name.
3666     /// </summary>
3667     /// <param name="fontFamilyName">Font family name</param>
3668     /// <param name="textRange">Text range to which this change applies.</param>
3669     /// <returns>
3670     /// Standard HRESULT error code.
3671     /// </returns>
3672     STDMETHOD(SetFontFamilyName)(
3673         __in_z WCHAR const* fontFamilyName,
3674         DWRITE_TEXT_RANGE textRange
3675         ) PURE;
3676 
3677     /// <summary>
3678     /// Set font weight.
3679     /// </summary>
3680     /// <param name="fontWeight">Font weight</param>
3681     /// <param name="textRange">Text range to which this change applies.</param>
3682     /// <returns>
3683     /// Standard HRESULT error code.
3684     /// </returns>
3685     STDMETHOD(SetFontWeight)(
3686         DWRITE_FONT_WEIGHT fontWeight,
3687         DWRITE_TEXT_RANGE textRange
3688         ) PURE;
3689 
3690     /// <summary>
3691     /// Set font style.
3692     /// </summary>
3693     /// <param name="fontStyle">Font style</param>
3694     /// <param name="textRange">Text range to which this change applies.</param>
3695     /// <returns>
3696     /// Standard HRESULT error code.
3697     /// </returns>
3698     STDMETHOD(SetFontStyle)(
3699         DWRITE_FONT_STYLE fontStyle,
3700         DWRITE_TEXT_RANGE textRange
3701         ) PURE;
3702 
3703     /// <summary>
3704     /// Set font stretch.
3705     /// </summary>
3706     /// <param name="fontStretch">font stretch</param>
3707     /// <param name="textRange">Text range to which this change applies.</param>
3708     /// <returns>
3709     /// Standard HRESULT error code.
3710     /// </returns>
3711     STDMETHOD(SetFontStretch)(
3712         DWRITE_FONT_STRETCH fontStretch,
3713         DWRITE_TEXT_RANGE textRange
3714         ) PURE;
3715 
3716     /// <summary>
3717     /// Set font em height.
3718     /// </summary>
3719     /// <param name="fontSize">Font em height</param>
3720     /// <param name="textRange">Text range to which this change applies.</param>
3721     /// <returns>
3722     /// Standard HRESULT error code.
3723     /// </returns>
3724     STDMETHOD(SetFontSize)(
3725         FLOAT fontSize,
3726         DWRITE_TEXT_RANGE textRange
3727         ) PURE;
3728 
3729     /// <summary>
3730     /// Set underline.
3731     /// </summary>
3732     /// <param name="hasUnderline">The Boolean flag indicates whether underline takes place</param>
3733     /// <param name="textRange">Text range to which this change applies.</param>
3734     /// <returns>
3735     /// Standard HRESULT error code.
3736     /// </returns>
3737     STDMETHOD(SetUnderline)(
3738         BOOL hasUnderline,
3739         DWRITE_TEXT_RANGE textRange
3740         ) PURE;
3741 
3742     /// <summary>
3743     /// Set strikethrough.
3744     /// </summary>
3745     /// <param name="hasStrikethrough">The Boolean flag indicates whether strikethrough takes place</param>
3746     /// <param name="textRange">Text range to which this change applies.</param>
3747     /// <returns>
3748     /// Standard HRESULT error code.
3749     /// </returns>
3750     STDMETHOD(SetStrikethrough)(
3751         BOOL hasStrikethrough,
3752         DWRITE_TEXT_RANGE textRange
3753         ) PURE;
3754 
3755     /// <summary>
3756     /// Set application-defined drawing effect.
3757     /// </summary>
3758     /// <param name="drawingEffect">Pointer to an application-defined drawing effect.</param>
3759     /// <param name="textRange">Text range to which this change applies.</param>
3760     /// <returns>
3761     /// Standard HRESULT error code.
3762     /// </returns>
3763     /// <remarks>
3764     /// This drawing effect is associated with the specified range and will be passed back
3765     /// to the application via the callback when the range is drawn at drawing time.
3766     /// </remarks>
3767     STDMETHOD(SetDrawingEffect)(
3768         IUnknown* drawingEffect,
3769         DWRITE_TEXT_RANGE textRange
3770         ) PURE;
3771 
3772     /// <summary>
3773     /// Set inline object.
3774     /// </summary>
3775     /// <param name="inlineObject">Pointer to an application-implemented inline object.</param>
3776     /// <param name="textRange">Text range to which this change applies.</param>
3777     /// <returns>
3778     /// Standard HRESULT error code.
3779     /// </returns>
3780     /// <remarks>
3781     /// This inline object applies to the specified range and will be passed back
3782     /// to the application via the DrawInlineObject callback when the range is drawn.
3783     /// Any text in that range will be suppressed.
3784     /// </remarks>
3785     STDMETHOD(SetInlineObject)(
3786         IDWriteInlineObject* inlineObject,
3787         DWRITE_TEXT_RANGE textRange
3788         ) PURE;
3789 
3790     /// <summary>
3791     /// Set font typography features.
3792     /// </summary>
3793     /// <param name="typography">Pointer to font typography setting.</param>
3794     /// <param name="textRange">Text range to which this change applies.</param>
3795     /// <returns>
3796     /// Standard HRESULT error code.
3797     /// </returns>
3798     STDMETHOD(SetTypography)(
3799         IDWriteTypography* typography,
3800         DWRITE_TEXT_RANGE textRange
3801         ) PURE;
3802 
3803     /// <summary>
3804     /// Set locale name.
3805     /// </summary>
3806     /// <param name="localeName">Locale name</param>
3807     /// <param name="textRange">Text range to which this change applies.</param>
3808     /// <returns>
3809     /// Standard HRESULT error code.
3810     /// </returns>
3811     STDMETHOD(SetLocaleName)(
3812         __in_z WCHAR const* localeName,
3813         DWRITE_TEXT_RANGE textRange
3814         ) PURE;
3815 
3816     /// <summary>
3817     /// Get layout maximum width
3818     /// </summary>
3819     STDMETHOD_(FLOAT, GetMaxWidth)() PURE;
3820 
3821     /// <summary>
3822     /// Get layout maximum height
3823     /// </summary>
3824     STDMETHOD_(FLOAT, GetMaxHeight)() PURE;
3825 
3826     /// <summary>
3827     /// Get the font collection where the current position is at.
3828     /// </summary>
3829     /// <param name="currentPosition">The current text position.</param>
3830     /// <param name="fontCollection">The current font collection</param>
3831     /// <param name="textRange">Text range to which this change applies.</param>
3832     /// <returns>
3833     /// Standard HRESULT error code.
3834     /// </returns>
3835     STDMETHOD(GetFontCollection)(
3836         UINT32 currentPosition,
3837         __out IDWriteFontCollection** fontCollection,
3838         __out_opt DWRITE_TEXT_RANGE* textRange = NULL
3839         ) PURE;
3840 
3841     /// <summary>
3842     /// Get the length of the font family name where the current position is at.
3843     /// </summary>
3844     /// <param name="currentPosition">The current text position.</param>
3845     /// <param name="nameLength">Size of the character array in character count not including the terminated NULL character.</param>
3846     /// <param name="textRange">The position range of the current format.</param>
3847     /// <returns>
3848     /// Standard HRESULT error code.
3849     /// </returns>
3850     STDMETHOD(GetFontFamilyNameLength)(
3851         UINT32 currentPosition,
3852         __out UINT32* nameLength,
3853         __out_opt DWRITE_TEXT_RANGE* textRange = NULL
3854         ) PURE;
3855 
3856     /// <summary>
3857     /// Copy the font family name where the current position is at.
3858     /// </summary>
3859     /// <param name="currentPosition">The current text position.</param>
3860     /// <param name="fontFamilyName">Character array that receives the current font family name</param>
3861     /// <param name="nameSize">Size of the character array in character count including the terminated NULL character.</param>
3862     /// <param name="textRange">The position range of the current format.</param>
3863     /// <returns>
3864     /// Standard HRESULT error code.
3865     /// </returns>
3866     STDMETHOD(GetFontFamilyName)(
3867         UINT32 currentPosition,
3868         __out_ecount_z(nameSize) WCHAR* fontFamilyName,
3869         UINT32 nameSize,
3870         __out_opt DWRITE_TEXT_RANGE* textRange = NULL
3871         ) PURE;
3872 
3873     /// <summary>
3874     /// Get the font weight where the current position is at.
3875     /// </summary>
3876     /// <param name="currentPosition">The current text position.</param>
3877     /// <param name="fontWeight">The current font weight</param>
3878     /// <param name="textRange">The position range of the current format.</param>
3879     /// <returns>
3880     /// Standard HRESULT error code.
3881     /// </returns>
3882     STDMETHOD(GetFontWeight)(
3883         UINT32 currentPosition,
3884         __out DWRITE_FONT_WEIGHT* fontWeight,
3885         __out_opt DWRITE_TEXT_RANGE* textRange = NULL
3886         ) PURE;
3887 
3888     /// <summary>
3889     /// Get the font style where the current position is at.
3890     /// </summary>
3891     /// <param name="currentPosition">The current text position.</param>
3892     /// <param name="fontStyle">The current font style</param>
3893     /// <param name="textRange">The position range of the current format.</param>
3894     /// <returns>
3895     /// Standard HRESULT error code.
3896     /// </returns>
3897     STDMETHOD(GetFontStyle)(
3898         UINT32 currentPosition,
3899         __out DWRITE_FONT_STYLE* fontStyle,
3900         __out_opt DWRITE_TEXT_RANGE* textRange = NULL
3901         ) PURE;
3902 
3903     /// <summary>
3904     /// Get the font stretch where the current position is at.
3905     /// </summary>
3906     /// <param name="currentPosition">The current text position.</param>
3907     /// <param name="fontStretch">The current font stretch</param>
3908     /// <param name="textRange">The position range of the current format.</param>
3909     /// <returns>
3910     /// Standard HRESULT error code.
3911     /// </returns>
3912     STDMETHOD(GetFontStretch)(
3913         UINT32 currentPosition,
3914         __out DWRITE_FONT_STRETCH* fontStretch,
3915         __out_opt DWRITE_TEXT_RANGE* textRange = NULL
3916         ) PURE;
3917 
3918     /// <summary>
3919     /// Get the font em height where the current position is at.
3920     /// </summary>
3921     /// <param name="currentPosition">The current text position.</param>
3922     /// <param name="fontSize">The current font em height</param>
3923     /// <param name="textRange">The position range of the current format.</param>
3924     /// <returns>
3925     /// Standard HRESULT error code.
3926     /// </returns>
3927     STDMETHOD(GetFontSize)(
3928         UINT32 currentPosition,
3929         __out FLOAT* fontSize,
3930         __out_opt DWRITE_TEXT_RANGE* textRange = NULL
3931         ) PURE;
3932 
3933     /// <summary>
3934     /// Get the underline presence where the current position is at.
3935     /// </summary>
3936     /// <param name="currentPosition">The current text position.</param>
3937     /// <param name="hasUnderline">The Boolean flag indicates whether text is underlined.</param>
3938     /// <param name="textRange">The position range of the current format.</param>
3939     /// <returns>
3940     /// Standard HRESULT error code.
3941     /// </returns>
3942     STDMETHOD(GetUnderline)(
3943         UINT32 currentPosition,
3944         __out BOOL* hasUnderline,
3945         __out_opt DWRITE_TEXT_RANGE* textRange = NULL
3946         ) PURE;
3947 
3948     /// <summary>
3949     /// Get the strikethrough presence where the current position is at.
3950     /// </summary>
3951     /// <param name="currentPosition">The current text position.</param>
3952     /// <param name="hasStrikethrough">The Boolean flag indicates whether text has strikethrough.</param>
3953     /// <param name="textRange">The position range of the current format.</param>
3954     /// <returns>
3955     /// Standard HRESULT error code.
3956     /// </returns>
3957     STDMETHOD(GetStrikethrough)(
3958         UINT32 currentPosition,
3959         __out BOOL* hasStrikethrough,
3960         __out_opt DWRITE_TEXT_RANGE* textRange = NULL
3961         ) PURE;
3962 
3963     /// <summary>
3964     /// Get the application-defined drawing effect where the current position is at.
3965     /// </summary>
3966     /// <param name="currentPosition">The current text position.</param>
3967     /// <param name="drawingEffect">The current application-defined drawing effect.</param>
3968     /// <param name="textRange">The position range of the current format.</param>
3969     /// <returns>
3970     /// Standard HRESULT error code.
3971     /// </returns>
3972     STDMETHOD(GetDrawingEffect)(
3973         UINT32 currentPosition,
3974         __out IUnknown** drawingEffect,
3975         __out_opt DWRITE_TEXT_RANGE* textRange = NULL
3976         ) PURE;
3977 
3978     /// <summary>
3979     /// Get the inline object at the given position.
3980     /// </summary>
3981     /// <param name="currentPosition">The given text position.</param>
3982     /// <param name="inlineObject">The inline object.</param>
3983     /// <param name="textRange">The position range of the current format.</param>
3984     /// <returns>
3985     /// Standard HRESULT error code.
3986     /// </returns>
3987     STDMETHOD(GetInlineObject)(
3988         UINT32 currentPosition,
3989         __out IDWriteInlineObject** inlineObject,
3990         __out_opt DWRITE_TEXT_RANGE* textRange = NULL
3991         ) PURE;
3992 
3993     /// <summary>
3994     /// Get the typography setting where the current position is at.
3995     /// </summary>
3996     /// <param name="currentPosition">The current text position.</param>
3997     /// <param name="typography">The current typography setting.</param>
3998     /// <param name="textRange">The position range of the current format.</param>
3999     /// <returns>
4000     /// Standard HRESULT error code.
4001     /// </returns>
4002     STDMETHOD(GetTypography)(
4003         UINT32 currentPosition,
4004         __out IDWriteTypography** typography,
4005         __out_opt DWRITE_TEXT_RANGE* textRange = NULL
4006         ) PURE;
4007 
4008     /// <summary>
4009     /// Get the length of the locale name where the current position is at.
4010     /// </summary>
4011     /// <param name="currentPosition">The current text position.</param>
4012     /// <param name="nameLength">Size of the character array in character count not including the terminated NULL character.</param>
4013     /// <param name="textRange">The position range of the current format.</param>
4014     /// <returns>
4015     /// Standard HRESULT error code.
4016     /// </returns>
4017     STDMETHOD(GetLocaleNameLength)(
4018         UINT32 currentPosition,
4019         __out UINT32* nameLength,
4020         __out_opt DWRITE_TEXT_RANGE* textRange = NULL
4021         ) PURE;
4022 
4023     /// <summary>
4024     /// Get the locale name where the current position is at.
4025     /// </summary>
4026     /// <param name="currentPosition">The current text position.</param>
4027     /// <param name="localeName">Character array that receives the current locale name</param>
4028     /// <param name="nameSize">Size of the character array in character count including the terminated NULL character.</param>
4029     /// <param name="textRange">The position range of the current format.</param>
4030     /// <returns>
4031     /// Standard HRESULT error code.
4032     /// </returns>
4033     STDMETHOD(GetLocaleName)(
4034         UINT32 currentPosition,
4035         __out_ecount_z(nameSize) WCHAR* localeName,
4036         UINT32 nameSize,
4037         __out_opt DWRITE_TEXT_RANGE* textRange = NULL
4038         ) PURE;
4039 
4040     /// <summary>
4041     /// Initiate drawing of the text.
4042     /// </summary>
4043     /// <param name="clientDrawingContext">An application defined value
4044     /// included in rendering callbacks.</param>
4045     /// <param name="renderer">The set of application-defined callbacks that do
4046     /// the actual rendering.</param>
4047     /// <param name="originX">X-coordinate of the layout's left side.</param>
4048     /// <param name="originY">Y-coordinate of the layout's top side.</param>
4049     /// <returns>
4050     /// Standard HRESULT error code.
4051     /// </returns>
4052     STDMETHOD(Draw)(
4053         __maybenull void* clientDrawingContext,
4054         IDWriteTextRenderer* renderer,
4055         FLOAT originX,
4056         FLOAT originY
4057         ) PURE;
4058 
4059     /// <summary>
4060     /// GetLineMetrics returns properties of each line.
4061     /// </summary>
4062     /// <param name="lineMetrics">The array to fill with line information.</param>
4063     /// <param name="maxLineCount">The maximum size of the lineMetrics array.</param>
4064     /// <param name="actualLineCount">The actual size of the lineMetrics
4065     /// array that is needed.</param>
4066     /// <returns>
4067     /// Standard HRESULT error code.
4068     /// </returns>
4069     /// <remarks>
4070     /// If maxLineCount is not large enough E_NOT_SUFFICIENT_BUFFER,
4071     /// which is equivalent to HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER),
4072     /// is returned and *actualLineCount is set to the number of lines
4073     /// needed.
4074     /// </remarks>
4075     STDMETHOD(GetLineMetrics)(
4076         __out_ecount_opt(maxLineCount) DWRITE_LINE_METRICS* lineMetrics,
4077         UINT32 maxLineCount,
4078         __out UINT32* actualLineCount
4079         ) PURE;
4080 
4081     /// <summary>
4082     /// GetMetrics retrieves overall metrics for the formatted string.
4083     /// </summary>
4084     /// <param name="textMetrics">The returned metrics.</param>
4085     /// <returns>
4086     /// Standard HRESULT error code.
4087     /// </returns>
4088     /// <remarks>
4089     /// Drawing effects like underline and strikethrough do not contribute
4090     /// to the text size, which is essentially the sum of advance widths and
4091     /// line heights. Additionally, visible swashes and other graphic
4092     /// adornments may extend outside the returned width and height.
4093     /// </remarks>
4094     STDMETHOD(GetMetrics)(
4095         __out DWRITE_TEXT_METRICS* textMetrics
4096         ) PURE;
4097 
4098     /// <summary>
4099     /// GetOverhangMetrics returns the overhangs (in DIPs) of the layout and all
4100     /// objects contained in it, including text glyphs and inline objects.
4101     /// </summary>
4102     /// <param name="overhangs">Overshoots of visible extents (in DIPs) outside the layout.</param>
4103     /// <returns>
4104     /// Standard HRESULT error code.
4105     /// </returns>
4106     /// <remarks>
4107     /// Any underline and strikethrough do not contribute to the black box
4108     /// determination, since these are actually drawn by the renderer, which
4109     /// is allowed to draw them in any variety of styles.
4110     /// </remarks>
4111     STDMETHOD(GetOverhangMetrics)(
4112         __out DWRITE_OVERHANG_METRICS* overhangs
4113         ) PURE;
4114 
4115     /// <summary>
4116     /// Retrieve logical properties and measurement of each cluster.
4117     /// </summary>
4118     /// <param name="clusterMetrics">The array to fill with cluster information.</param>
4119     /// <param name="maxClusterCount">The maximum size of the clusterMetrics array.</param>
4120     /// <param name="actualClusterCount">The actual size of the clusterMetrics array that is needed.</param>
4121     /// <returns>
4122     /// Standard HRESULT error code.
4123     /// </returns>
4124     /// <remarks>
4125     /// If maxClusterCount is not large enough E_NOT_SUFFICIENT_BUFFER,
4126     /// which is equivalent to HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER),
4127     /// is returned and *actualClusterCount is set to the number of clusters
4128     /// needed.
4129     /// </remarks>
4130     STDMETHOD(GetClusterMetrics)(
4131         __out_ecount_opt(maxClusterCount) DWRITE_CLUSTER_METRICS* clusterMetrics,
4132         UINT32 maxClusterCount,
4133         __out UINT32* actualClusterCount
4134         ) PURE;
4135 
4136     /// <summary>
4137     /// Determines the minimum possible width the layout can be set to without
4138     /// emergency breaking between the characters of whole words.
4139     /// </summary>
4140     /// <param name="minWidth">Minimum width.</param>
4141     /// <returns>
4142     /// Standard HRESULT error code.
4143     /// </returns>
4144     STDMETHOD(DetermineMinWidth)(
4145         __out FLOAT* minWidth
4146         ) PURE;
4147 
4148     /// <summary>
4149     /// Given a coordinate (in DIPs) relative to the top-left of the layout box,
4150     /// this returns the corresponding hit-test metrics of the text string where
4151     /// the hit-test has occurred. This is useful for mapping mouse clicks to caret
4152     /// positions. When the given coordinate is outside the text string, the function
4153     /// sets the output value *isInside to false but returns the nearest character
4154     /// position.
4155     /// </summary>
4156     /// <param name="pointX">X coordinate to hit-test, relative to the top-left location of the layout box.</param>
4157     /// <param name="pointY">Y coordinate to hit-test, relative to the top-left location of the layout box.</param>
4158     /// <param name="isTrailingHit">Output flag indicating whether the hit-test location is at the leading or the trailing
4159     ///     side of the character. When the output *isInside value is set to false, this value is set according to the output
4160     ///     *position value to represent the edge closest to the hit-test location. </param>
4161     /// <param name="isInside">Output flag indicating whether the hit-test location is inside the text string.
4162     ///     When false, the position nearest the text's edge is returned.</param>
4163     /// <param name="hitTestMetrics">Output geometry fully enclosing the hit-test location. When the output *isInside value
4164     ///     is set to false, this structure represents the geometry enclosing the edge closest to the hit-test location.</param>
4165     /// <returns>
4166     /// Standard HRESULT error code.
4167     /// </returns>
4168     STDMETHOD(HitTestPoint)(
4169         FLOAT pointX,
4170         FLOAT pointY,
4171         __out BOOL* isTrailingHit,
4172         __out BOOL* isInside,
4173         __out DWRITE_HIT_TEST_METRICS* hitTestMetrics
4174         ) PURE;
4175 
4176     /// <summary>
4177     /// Given a text position and whether the caret is on the leading or trailing
4178     /// edge of that position, this returns the corresponding coordinate (in DIPs)
4179     /// relative to the top-left of the layout box. This is most useful for drawing
4180     /// the caret's current position, but it could also be used to anchor an IME to the
4181     /// typed text or attach a floating menu near the point of interest. It may also be
4182     /// used to programmatically obtain the geometry of a particular text position
4183     /// for UI automation.
4184     /// </summary>
4185     /// <param name="textPosition">Text position to get the coordinate of.</param>
4186     /// <param name="isTrailingHit">Flag indicating whether the location is of the leading or the trailing side of the specified text position. </param>
4187     /// <param name="pointX">Output caret X, relative to the top-left of the layout box.</param>
4188     /// <param name="pointY">Output caret Y, relative to the top-left of the layout box.</param>
4189     /// <param name="hitTestMetrics">Output geometry fully enclosing the specified text position.</param>
4190     /// <returns>
4191     /// Standard HRESULT error code.
4192     /// </returns>
4193     /// <remarks>
4194     /// When drawing a caret at the returned X,Y, it should should be centered on X
4195     /// and drawn from the Y coordinate down. The height will be the size of the
4196     /// hit-tested text (which can vary in size within a line).
4197     /// Reading direction also affects which side of the character the caret is drawn.
4198     /// However, the returned X coordinate will be correct for either case.
4199     /// You can get a text length back that is larger than a single character.
4200     /// This happens for complex scripts when multiple characters form a single cluster,
4201     /// when diacritics join their base character, or when you test a surrogate pair.
4202     /// </remarks>
4203     STDMETHOD(HitTestTextPosition)(
4204         UINT32 textPosition,
4205         BOOL isTrailingHit,
4206         __out FLOAT* pointX,
4207         __out FLOAT* pointY,
4208         __out DWRITE_HIT_TEST_METRICS* hitTestMetrics
4209         ) PURE;
4210 
4211     /// <summary>
4212     /// The application calls this function to get a set of hit-test metrics
4213     /// corresponding to a range of text positions. The main usage for this
4214     /// is to draw highlighted selection of the text string.
4215     ///
4216     /// The function returns E_NOT_SUFFICIENT_BUFFER, which is equivalent to
4217     /// HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER), when the buffer size of
4218     /// hitTestMetrics is too small to hold all the regions calculated by the
4219     /// function. In such situation, the function sets the output value
4220     /// *actualHitTestMetricsCount to the number of geometries calculated.
4221     /// The application is responsible to allocate a new buffer of greater
4222     /// size and call the function again.
4223     ///
4224     /// A good value to use as an initial value for maxHitTestMetricsCount may
4225     /// be calculated from the following equation:
4226     ///     maxHitTestMetricsCount = lineCount * maxBidiReorderingDepth
4227     ///
4228     /// where lineCount is obtained from the value of the output argument
4229     /// *actualLineCount from the function IDWriteTextLayout::GetLineMetrics,
4230     /// and the maxBidiReorderingDepth value from the DWRITE_TEXT_METRICS
4231     /// structure of the output argument *textMetrics from the function
4232     /// IDWriteFactory::CreateTextLayout.
4233     /// </summary>
4234     /// <param name="textPosition">First text position of the specified range.</param>
4235     /// <param name="textLength">Number of positions of the specified range.</param>
4236     /// <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>
4237     /// <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>
4238     /// <param name="hitTestMetrics">Pointer to a buffer of the output geometry fully enclosing the specified position range.</param>
4239     /// <param name="maxHitTestMetricsCount">Maximum number of distinct metrics it could hold in its buffer memory.</param>
4240     /// <param name="actualHitTestMetricsCount">Actual number of metrics returned or needed.</param>
4241     /// <returns>
4242     /// Standard HRESULT error code.
4243     /// </returns>
4244     /// <remarks>
4245     /// There are no gaps in the returned metrics. While there could be visual gaps,
4246     /// depending on bidi ordering, each range is contiguous and reports all the text,
4247     /// including any hidden characters and trimmed text.
4248     /// The height of each returned range will be the same within each line, regardless
4249     /// of how the font sizes vary.
4250     /// </remarks>
4251     STDMETHOD(HitTestTextRange)(
4252         UINT32 textPosition,
4253         UINT32 textLength,
4254         FLOAT originX,
4255         FLOAT originY,
4256         __out_ecount_opt(maxHitTestMetricsCount) DWRITE_HIT_TEST_METRICS* hitTestMetrics,
4257         UINT32 maxHitTestMetricsCount,
4258         __out UINT32* actualHitTestMetricsCount
4259         ) PURE;
4260 };
4261 
4262 /// <summary>
4263 /// Encapsulates a 32-bit device independent bitmap and device context, which can be used for rendering glyphs.
4264 /// </summary>
4265 interface DWRITE_DECLARE_INTERFACE("5e5a32a3-8dff-4773-9ff6-0696eab77267") IDWriteBitmapRenderTarget : public IUnknown
4266 {
4267     /// <summary>
4268     /// Draws a run of glyphs to the bitmap.
4269     /// </summary>
4270     /// <param name="baselineOriginX">Horizontal position of the baseline origin, in DIPs, relative to the upper-left corner of the DIB.</param>
4271     /// <param name="baselineOriginY">Vertical position of the baseline origin, in DIPs, relative to the upper-left corner of the DIB.</param>
4272     /// <param name="measuringMode">Specifies measuring method for glyphs in the run.
4273     /// Renderer implementations may choose different rendering modes for different measuring methods, for example
4274     /// DWRITE_RENDERING_MODE_CLEARTYPE_NATURAL for DWRITE_MEASURING_MODE_NATURAL,
4275     /// DWRITE_RENDERING_MODE_CLEARTYPE_GDI_CLASSIC for DWRITE_MEASURING_MODE_GDI_CLASSIC, and
4276     /// DWRITE_RENDERING_MODE_CLEARTYPE_GDI_NATURAL for DWRITE_MEASURING_MODE_GDI_NATURAL.
4277     /// </param>
4278     /// <param name="glyphRun">Structure containing the properties of the glyph run.</param>
4279     /// <param name="renderingParams">Object that controls rendering behavior.</param>
4280     /// <param name="textColor">Specifies the foreground color of the text.</param>
4281     /// <param name="blackBoxRect">Optional rectangle that receives the bounding box (in pixels not DIPs) of all the pixels affected by
4282     /// drawing the glyph run. The black box rectangle may extend beyond the dimensions of the bitmap.</param>
4283     /// <returns>
4284     /// Standard HRESULT error code.
4285     /// </returns>
4286     STDMETHOD(DrawGlyphRun)(
4287         FLOAT baselineOriginX,
4288         FLOAT baselineOriginY,
4289         DWRITE_MEASURING_MODE measuringMode,
4290         __in DWRITE_GLYPH_RUN const* glyphRun,
4291         IDWriteRenderingParams* renderingParams,
4292         COLORREF textColor,
4293         __out_opt RECT* blackBoxRect = NULL
4294         ) PURE;
4295 
4296     /// <summary>
4297     /// Gets a handle to the memory device context.
4298     /// </summary>
4299     /// <returns>
4300     /// Returns the device context handle.
4301     /// </returns>
4302     /// <remarks>
4303     /// An application can use the device context to draw using GDI functions. An application can obtain the bitmap handle
4304     /// (HBITMAP) by calling GetCurrentObject. An application that wants information about the underlying bitmap, including
4305     /// a pointer to the pixel data, can call GetObject to fill in a DIBSECTION structure. The bitmap is always a 32-bit
4306     /// top-down DIB.
4307     /// </remarks>
4308     STDMETHOD_(HDC, GetMemoryDC)() PURE;
4309 
4310     /// <summary>
4311     /// Gets the number of bitmap pixels per DIP. A DIP (device-independent pixel) is 1/96 inch so this value is the number
4312     /// if pixels per inch divided by 96.
4313     /// </summary>
4314     /// <returns>
4315     /// Returns the number of bitmap pixels per DIP.
4316     /// </returns>
4317     STDMETHOD_(FLOAT, GetPixelsPerDip)() PURE;
4318 
4319     /// <summary>
4320     /// Sets the number of bitmap pixels per DIP. A DIP (device-independent pixel) is 1/96 inch so this value is the number
4321     /// if pixels per inch divided by 96.
4322     /// </summary>
4323     /// <param name="pixelsPerDip">Specifies the number of pixels per DIP.</param>
4324     /// <returns>
4325     /// Standard HRESULT error code.
4326     /// </returns>
4327     STDMETHOD(SetPixelsPerDip)(
4328         FLOAT pixelsPerDip
4329         ) PURE;
4330 
4331     /// <summary>
4332     /// Gets the transform that maps abstract coordinate to DIPs. By default this is the identity
4333     /// transform. Note that this is unrelated to the world transform of the underlying device
4334     /// context.
4335     /// </summary>
4336     /// <param name="transform">Receives the transform.</param>
4337     /// <returns>
4338     /// Standard HRESULT error code.
4339     /// </returns>
4340     STDMETHOD(GetCurrentTransform)(
4341         __out DWRITE_MATRIX* transform
4342         ) PURE;
4343 
4344     /// <summary>
4345     /// Sets the transform that maps abstract coordinate to DIPs. This does not affect the world
4346     /// transform of the underlying device context.
4347     /// </summary>
4348     /// <param name="transform">Specifies the new transform. This parameter can be NULL, in which
4349     /// case the identity transform is implied.</param>
4350     /// <returns>
4351     /// Standard HRESULT error code.
4352     /// </returns>
4353     STDMETHOD(SetCurrentTransform)(
4354         __in_opt DWRITE_MATRIX const* transform
4355         ) PURE;
4356 
4357     /// <summary>
4358     /// Gets the dimensions of the bitmap.
4359     /// </summary>
4360     /// <param name="size">Receives the size of the bitmap in pixels.</param>
4361     /// <returns>
4362     /// Standard HRESULT error code.
4363     /// </returns>
4364     STDMETHOD(GetSize)(
4365         __out SIZE* size
4366         ) PURE;
4367 
4368     /// <summary>
4369     /// Resizes the bitmap.
4370     /// </summary>
4371     /// <param name="width">New bitmap width, in pixels.</param>
4372     /// <param name="height">New bitmap height, in pixels.</param>
4373     /// <returns>
4374     /// Standard HRESULT error code.
4375     /// </returns>
4376     STDMETHOD(Resize)(
4377         UINT32 width,
4378         UINT32 height
4379         ) PURE;
4380 };
4381 
4382 /// <summary>
4383 /// The GDI interop interface provides interoperability with GDI.
4384 /// </summary>
4385 interface DWRITE_DECLARE_INTERFACE("1edd9491-9853-4299-898f-6432983b6f3a") IDWriteGdiInterop : public IUnknown
4386 {
4387     /// <summary>
4388     /// Creates a font object that matches the properties specified by the LOGFONT structure.
4389     /// </summary>
4390     /// <param name="logFont">Structure containing a GDI-compatible font description.</param>
4391     /// <param name="font">Receives a newly created font object if successful, or NULL in case of error.</param>
4392     /// <returns>
4393     /// Standard HRESULT error code.
4394     /// </returns>
4395     STDMETHOD(CreateFontFromLOGFONT)(
4396         __in LOGFONTW const* logFont,
4397         __out IDWriteFont** font
4398         ) PURE;
4399 
4400     /// <summary>
4401     /// Initializes a LOGFONT structure based on the GDI-compatible properties of the specified font.
4402     /// </summary>
4403     /// <param name="font">Specifies a font in the system font collection.</param>
4404     /// <param name="logFont">Structure that receives a GDI-compatible font description.</param>
4405     /// <param name="isSystemFont">Contains TRUE if the specified font object is part of the system font collection
4406     /// or FALSE otherwise.</param>
4407     /// <returns>
4408     /// Standard HRESULT error code.
4409     /// </returns>
4410     STDMETHOD(ConvertFontToLOGFONT)(
4411         IDWriteFont* font,
4412         __out LOGFONTW* logFont,
4413         __out BOOL* isSystemFont
4414         ) PURE;
4415 
4416     /// <summary>
4417     /// Initializes a LOGFONT structure based on the GDI-compatible properties of the specified font.
4418     /// </summary>
4419     /// <param name="font">Specifies a font face.</param>
4420     /// <param name="logFont">Structure that receives a GDI-compatible font description.</param>
4421     /// <returns>
4422     /// Standard HRESULT error code.
4423     /// </returns>
4424     STDMETHOD(ConvertFontFaceToLOGFONT)(
4425         IDWriteFontFace* font,
4426         __out LOGFONTW* logFont
4427         ) PURE;
4428 
4429     /// <summary>
4430     /// Creates a font face object that corresponds to the currently selected HFONT.
4431     /// </summary>
4432     /// <param name="hdc">Handle to a device context into which a font has been selected. It is assumed that the client
4433     /// has already performed font mapping and that the font selected into the DC is the actual font that would be used
4434     /// for rendering glyphs.</param>
4435     /// <param name="fontFace">Contains the newly created font face object, or NULL in case of failure.</param>
4436     /// <returns>
4437     /// Standard HRESULT error code.
4438     /// </returns>
4439     STDMETHOD(CreateFontFaceFromHdc)(
4440         HDC hdc,
4441         __out IDWriteFontFace** fontFace
4442         ) PURE;
4443 
4444     /// <summary>
4445     /// Creates an object that encapsulates a bitmap and memory DC which can be used for rendering glyphs.
4446     /// </summary>
4447     /// <param name="hdc">Optional device context used to create a compatible memory DC.</param>
4448     /// <param name="width">Width of the bitmap.</param>
4449     /// <param name="height">Height of the bitmap.</param>
4450     /// <param name="renderTarget">Receives a pointer to the newly created render target.</param>
4451     STDMETHOD(CreateBitmapRenderTarget)(
4452         __in_opt HDC hdc,
4453         UINT32 width,
4454         UINT32 height,
4455         __out IDWriteBitmapRenderTarget** renderTarget
4456         ) PURE;
4457 };
4458 
4459 /// <summary>
4460 /// The DWRITE_TEXTURE_TYPE enumeration identifies a type of alpha texture. An alpha texture is a bitmap of alpha values, each
4461 /// representing the darkness (i.e., opacity) of a pixel or subpixel.
4462 /// </summary>
4463 enum DWRITE_TEXTURE_TYPE
4464 {
4465     /// <summary>
4466     /// Specifies an alpha texture for aliased text rendering (i.e., bi-level, where each pixel is either fully opaque or fully transparent),
4467     /// with one byte per pixel.
4468     /// </summary>
4469     DWRITE_TEXTURE_ALIASED_1x1,
4470 
4471     /// <summary>
4472     /// Specifies an alpha texture for ClearType text rendering, with three bytes per pixel in the horizontal dimension and
4473     /// one byte per pixel in the vertical dimension.
4474     /// </summary>
4475     DWRITE_TEXTURE_CLEARTYPE_3x1
4476 };
4477 
4478 /// <summary>
4479 /// Maximum alpha value in a texture returned by IDWriteGlyphRunAnalysis::CreateAlphaTexture.
4480 /// </summary>
4481 #define DWRITE_ALPHA_MAX 255
4482 
4483 /// <summary>
4484 /// Interface that encapsulates information used to render a glyph run.
4485 /// </summary>
4486 interface DWRITE_DECLARE_INTERFACE("7d97dbf7-e085-42d4-81e3-6a883bded118") IDWriteGlyphRunAnalysis : public IUnknown
4487 {
4488     /// <summary>
4489     /// Gets the bounding rectangle of the physical pixels affected by the glyph run.
4490     /// </summary>
4491     /// <param name="textureType">Specifies the type of texture requested. If a bi-level texture is requested, the
4492     /// bounding rectangle includes only bi-level glyphs. Otherwise, the bounding rectangle includes only anti-aliased
4493     /// glyphs.</param>
4494     /// <param name="textureBounds">Receives the bounding rectangle, or an empty rectangle if there are no glyphs
4495     /// if the specified type.</param>
4496     /// <returns>
4497     /// Standard HRESULT error code.
4498     /// </returns>
4499     STDMETHOD(GetAlphaTextureBounds)(
4500         DWRITE_TEXTURE_TYPE textureType,
4501         __out RECT* textureBounds
4502         ) PURE;
4503 
4504     /// <summary>
4505     /// Creates an alpha texture of the specified type.
4506     /// </summary>
4507     /// <param name="textureType">Specifies the type of texture requested. If a bi-level texture is requested, the
4508     /// texture contains only bi-level glyphs. Otherwise, the texture contains only anti-aliased glyphs.</param>
4509     /// <param name="textureBounds">Specifies the bounding rectangle of the texture, which can be different than
4510     /// the bounding rectangle returned by GetAlphaTextureBounds.</param>
4511     /// <param name="alphaValues">Receives the array of alpha values.</param>
4512     /// <param name="bufferSize">Size of the alphaValues array. The minimum size depends on the dimensions of the
4513     /// rectangle and the type of texture requested.</param>
4514     /// <returns>
4515     /// Standard HRESULT error code.
4516     /// </returns>
4517     STDMETHOD(CreateAlphaTexture)(
4518         DWRITE_TEXTURE_TYPE textureType,
4519         __in RECT const* textureBounds,
4520         __out_bcount(bufferSize) BYTE* alphaValues,
4521         UINT32 bufferSize
4522         ) PURE;
4523 
4524     /// <summary>
4525     /// Gets properties required for ClearType blending.
4526     /// </summary>
4527     /// <param name="renderingParams">Rendering parameters object. In most cases, the values returned in the output
4528     /// parameters are based on the properties of this object. The exception is if a GDI-compatible rendering mode
4529     /// is specified.</param>
4530     /// <param name="blendGamma">Receives the gamma value to use for gamma correction.</param>
4531     /// <param name="blendEnhancedContrast">Receives the enhanced contrast value.</param>
4532     /// <param name="blendClearTypeLevel">Receives the ClearType level.</param>
4533     STDMETHOD(GetAlphaBlendParams)(
4534         IDWriteRenderingParams* renderingParams,
4535         __out FLOAT* blendGamma,
4536         __out FLOAT* blendEnhancedContrast,
4537         __out FLOAT* blendClearTypeLevel
4538         ) PURE;
4539 };
4540 
4541 /// <summary>
4542 /// The root factory interface for all DWrite objects.
4543 /// </summary>
4544 interface DWRITE_DECLARE_INTERFACE("b859ee5a-d838-4b5b-a2e8-1adc7d93db48") IDWriteFactory : public IUnknown
4545 {
4546     /// <summary>
4547     /// Gets a font collection representing the set of installed fonts.
4548     /// </summary>
4549     /// <param name="fontCollection">Receives a pointer to the system font collection object, or NULL in case of failure.</param>
4550     /// <param name="checkForUpdates">If this parameter is nonzero, the function performs an immediate check for changes to the set of
4551     /// installed fonts. If this parameter is FALSE, the function will still detect changes if the font cache service is running, but
4552     /// there may be some latency. For example, an application might specify TRUE if it has itself just installed a font and wants to
4553     /// be sure the font collection contains that font.</param>
4554     /// <returns>
4555     /// Standard HRESULT error code.
4556     /// </returns>
4557     STDMETHOD(GetSystemFontCollection)(
4558         __out IDWriteFontCollection** fontCollection,
4559         BOOL checkForUpdates = FALSE
4560         ) PURE;
4561 
4562     /// <summary>
4563     /// Creates a font collection using a custom font collection loader.
4564     /// </summary>
4565     /// <param name="collectionLoader">Application-defined font collection loader, which must have been previously
4566     /// registered using RegisterFontCollectionLoader.</param>
4567     /// <param name="collectionKey">Key used by the loader to identify a collection of font files.</param>
4568     /// <param name="collectionKeySize">Size in bytes of the collection key.</param>
4569     /// <param name="fontCollection">Receives a pointer to the system font collection object, or NULL in case of failure.</param>
4570     /// <returns>
4571     /// Standard HRESULT error code.
4572     /// </returns>
4573     STDMETHOD(CreateCustomFontCollection)(
4574         IDWriteFontCollectionLoader* collectionLoader,
4575         __in_bcount(collectionKeySize) void const* collectionKey,
4576         UINT32 collectionKeySize,
4577         __out IDWriteFontCollection** fontCollection
4578         ) PURE;
4579 
4580     /// <summary>
4581     /// Registers a custom font collection loader with the factory object.
4582     /// </summary>
4583     /// <param name="fontCollectionLoader">Application-defined font collection loader.</param>
4584     /// <returns>
4585     /// Standard HRESULT error code.
4586     /// </returns>
4587     STDMETHOD(RegisterFontCollectionLoader)(
4588         IDWriteFontCollectionLoader* fontCollectionLoader
4589         ) PURE;
4590 
4591     /// <summary>
4592     /// Unregisters a custom font collection loader that was previously registered using RegisterFontCollectionLoader.
4593     /// </summary>
4594     /// <param name="fontCollectionLoader">Application-defined font collection loader.</param>
4595     /// <returns>
4596     /// Standard HRESULT error code.
4597     /// </returns>
4598     STDMETHOD(UnregisterFontCollectionLoader)(
4599         IDWriteFontCollectionLoader* fontCollectionLoader
4600         ) PURE;
4601 
4602     /// <summary>
4603     /// CreateFontFileReference creates a font file reference object from a local font file.
4604     /// </summary>
4605     /// <param name="filePath">Absolute file path. Subsequent operations on the constructed object may fail
4606     /// if the user provided filePath doesn't correspond to a valid file on the disk.</param>
4607     /// <param name="lastWriteTime">Last modified time of the input file path. If the parameter is omitted,
4608     /// the function will access the font file to obtain its last write time, so the clients are encouraged to specify this value
4609     /// to avoid extra disk access. Subsequent operations on the constructed object may fail
4610     /// if the user provided lastWriteTime doesn't match the file on the disk.</param>
4611     /// <param name="fontFile">Contains newly created font file reference object, or NULL in case of failure.</param>
4612     /// <returns>
4613     /// Standard HRESULT error code.
4614     /// </returns>
4615     STDMETHOD(CreateFontFileReference)(
4616         __in_z WCHAR const* filePath,
4617         __in_opt FILETIME const* lastWriteTime,
4618         __out IDWriteFontFile** fontFile
4619         ) PURE;
4620 
4621     /// <summary>
4622     /// CreateCustomFontFileReference creates a reference to an application specific font file resource.
4623     /// This function enables an application or a document to use a font without having to install it on the system.
4624     /// The fontFileReferenceKey has to be unique only in the scope of the fontFileLoader used in this call.
4625     /// </summary>
4626     /// <param name="fontFileReferenceKey">Font file reference key that uniquely identifies the font file resource
4627     /// during the lifetime of fontFileLoader.</param>
4628     /// <param name="fontFileReferenceKeySize">Size of font file reference key in bytes.</param>
4629     /// <param name="fontFileLoader">Font file loader that will be used by the font system to load data from the file identified by
4630     /// fontFileReferenceKey.</param>
4631     /// <param name="fontFile">Contains the newly created font file object, or NULL in case of failure.</param>
4632     /// <returns>
4633     /// Standard HRESULT error code.
4634     /// </returns>
4635     /// <remarks>
4636     /// This function is provided for cases when an application or a document needs to use a font
4637     /// without having to install it on the system. fontFileReferenceKey has to be unique only in the scope
4638     /// of the fontFileLoader used in this call.
4639     /// </remarks>
4640     STDMETHOD(CreateCustomFontFileReference)(
4641         __in_bcount(fontFileReferenceKeySize) void const* fontFileReferenceKey,
4642         UINT32 fontFileReferenceKeySize,
4643         IDWriteFontFileLoader* fontFileLoader,
4644         __out IDWriteFontFile** fontFile
4645         ) PURE;
4646 
4647     /// <summary>
4648     /// Creates a font face object.
4649     /// </summary>
4650     /// <param name="fontFaceType">The file format of the font face.</param>
4651     /// <param name="numberOfFiles">The number of font files require to represent the font face.</param>
4652     /// <param name="fontFiles">Font files representing the font face. Since IDWriteFontFace maintains its own references
4653     /// to the input font file objects, it's OK to release them after this call.</param>
4654     /// <param name="faceIndex">The zero based index of a font face in cases when the font files contain a collection of font faces.
4655     /// If the font files contain a single face, this value should be zero.</param>
4656     /// <param name="fontFaceSimulationFlags">Font face simulation flags for algorithmic emboldening and italicization.</param>
4657     /// <param name="fontFace">Contains the newly created font face object, or NULL in case of failure.</param>
4658     /// <returns>
4659     /// Standard HRESULT error code.
4660     /// </returns>
4661     STDMETHOD(CreateFontFace)(
4662         DWRITE_FONT_FACE_TYPE fontFaceType,
4663         UINT32 numberOfFiles,
4664         __in_ecount(numberOfFiles) IDWriteFontFile* const* fontFiles,
4665         UINT32 faceIndex,
4666         DWRITE_FONT_SIMULATIONS fontFaceSimulationFlags,
4667         __out IDWriteFontFace** fontFace
4668         ) PURE;
4669 
4670     /// <summary>
4671     /// Creates a rendering parameters object with default settings for the primary monitor.
4672     /// </summary>
4673     /// <param name="renderingParams">Holds the newly created rendering parameters object, or NULL in case of failure.</param>
4674     /// <returns>
4675     /// Standard HRESULT error code.
4676     /// </returns>
4677     STDMETHOD(CreateRenderingParams)(
4678         __out IDWriteRenderingParams** renderingParams
4679         ) PURE;
4680 
4681     /// <summary>
4682     /// Creates a rendering parameters object with default settings for the specified monitor.
4683     /// </summary>
4684     /// <param name="monitor">The monitor to read the default values from.</param>
4685     /// <param name="renderingParams">Holds the newly created rendering parameters object, or NULL in case of failure.</param>
4686     /// <returns>
4687     /// Standard HRESULT error code.
4688     /// </returns>
4689     STDMETHOD(CreateMonitorRenderingParams)(
4690         HMONITOR monitor,
4691         __out IDWriteRenderingParams** renderingParams
4692         ) PURE;
4693 
4694     /// <summary>
4695     /// Creates a rendering parameters object with the specified properties.
4696     /// </summary>
4697     /// <param name="gamma">The gamma value used for gamma correction, which must be greater than zero and cannot exceed 256.</param>
4698     /// <param name="enhancedContrast">The amount of contrast enhancement, zero or greater.</param>
4699     /// <param name="clearTypeLevel">The degree of ClearType level, from 0.0f (no ClearType) to 1.0f (full ClearType).</param>
4700     /// <param name="pixelGeometry">The geometry of a device pixel.</param>
4701     /// <param name="renderingMode">Method of rendering glyphs. In most cases, this should be DWRITE_RENDERING_MODE_DEFAULT to automatically use an appropriate mode.</param>
4702     /// <param name="renderingParams">Holds the newly created rendering parameters object, or NULL in case of failure.</param>
4703     /// <returns>
4704     /// Standard HRESULT error code.
4705     /// </returns>
4706     STDMETHOD(CreateCustomRenderingParams)(
4707         FLOAT gamma,
4708         FLOAT enhancedContrast,
4709         FLOAT clearTypeLevel,
4710         DWRITE_PIXEL_GEOMETRY pixelGeometry,
4711         DWRITE_RENDERING_MODE renderingMode,
4712         __out IDWriteRenderingParams** renderingParams
4713         ) PURE;
4714 
4715     /// <summary>
4716     /// Registers a font file loader with DirectWrite.
4717     /// </summary>
4718     /// <param name="fontFileLoader">Pointer to the implementation of the IDWriteFontFileLoader for a particular file resource type.</param>
4719     /// <returns>
4720     /// Standard HRESULT error code.
4721     /// </returns>
4722     /// <remarks>
4723     /// This function registers a font file loader with DirectWrite.
4724     /// Font file loader interface handles loading font file resources of a particular type from a key.
4725     /// The font file loader interface is recommended to be implemented by a singleton object.
4726     /// A given instance can only be registered once.
4727     /// Succeeding attempts will return an error that it has already been registered.
4728     /// IMPORTANT: font file loader implementations must not register themselves with DirectWrite
4729     /// inside their constructors and must not unregister themselves in their destructors, because
4730     /// registration and unregistraton operations increment and decrement the object reference count respectively.
4731     /// Instead, registration and unregistration of font file loaders with DirectWrite should be performed
4732     /// outside of the font file loader implementation as a separate step.
4733     /// </remarks>
4734     STDMETHOD(RegisterFontFileLoader)(
4735         IDWriteFontFileLoader* fontFileLoader
4736         ) PURE;
4737 
4738     /// <summary>
4739     /// Unregisters a font file loader that was previously registered with the DirectWrite font system using RegisterFontFileLoader.
4740     /// </summary>
4741     /// <param name="fontFileLoader">Pointer to the file loader that was previously registered with the DirectWrite font system using RegisterFontFileLoader.</param>
4742     /// <returns>
4743     /// This function will succeed if the user loader is requested to be removed.
4744     /// It will fail if the pointer to the file loader identifies a standard DirectWrite loader,
4745     /// or a loader that is never registered or has already been unregistered.
4746     /// </returns>
4747     /// <remarks>
4748     /// This function unregisters font file loader callbacks with the DirectWrite font system.
4749     /// The font file loader interface is recommended to be implemented by a singleton object.
4750     /// IMPORTANT: font file loader implementations must not register themselves with DirectWrite
4751     /// inside their constructors and must not unregister themselves in their destructors, because
4752     /// registration and unregistraton operations increment and decrement the object reference count respectively.
4753     /// Instead, registration and unregistration of font file loaders with DirectWrite should be performed
4754     /// outside of the font file loader implementation as a separate step.
4755     /// </remarks>
4756     STDMETHOD(UnregisterFontFileLoader)(
4757         IDWriteFontFileLoader* fontFileLoader
4758         ) PURE;
4759 
4760     /// <summary>
4761     /// Create a text format object used for text layout.
4762     /// </summary>
4763     /// <param name="fontFamilyName">Name of the font family</param>
4764     /// <param name="fontCollection">Font collection. NULL indicates the system font collection.</param>
4765     /// <param name="fontWeight">Font weight</param>
4766     /// <param name="fontStyle">Font style</param>
4767     /// <param name="fontStretch">Font stretch</param>
4768     /// <param name="fontSize">Logical size of the font in DIP units. A DIP ("device-independent pixel") equals 1/96 inch.</param>
4769     /// <param name="localeName">Locale name</param>
4770     /// <param name="textFormat">Contains newly created text format object, or NULL in case of failure.</param>
4771     /// <returns>
4772     /// Standard HRESULT error code.
4773     /// </returns>
4774     STDMETHOD(CreateTextFormat)(
4775         __in_z WCHAR const* fontFamilyName,
4776         __maybenull IDWriteFontCollection* fontCollection,
4777         DWRITE_FONT_WEIGHT fontWeight,
4778         DWRITE_FONT_STYLE fontStyle,
4779         DWRITE_FONT_STRETCH fontStretch,
4780         FLOAT fontSize,
4781         __in_z WCHAR const* localeName,
4782         __out IDWriteTextFormat** textFormat
4783         ) PURE;
4784 
4785     /// <summary>
4786     /// Create a typography object used in conjunction with text format for text layout.
4787     /// </summary>
4788     /// <param name="typography">Contains newly created typography object, or NULL in case of failure.</param>
4789     /// <returns>
4790     /// Standard HRESULT error code.
4791     /// </returns>
4792     STDMETHOD(CreateTypography)(
4793         __out IDWriteTypography** typography
4794         ) PURE;
4795 
4796     /// <summary>
4797     /// Create an object used for interoperability with GDI.
4798     /// </summary>
4799     /// <param name="gdiInterop">Receives the GDI interop object if successful, or NULL in case of failure.</param>
4800     /// <returns>
4801     /// Standard HRESULT error code.
4802     /// </returns>
4803     STDMETHOD(GetGdiInterop)(
4804         __out IDWriteGdiInterop** gdiInterop
4805         ) PURE;
4806 
4807     /// <summary>
4808     /// CreateTextLayout takes a string, format, and associated constraints
4809     /// and produces and object representing the fully analyzed
4810     /// and formatted result.
4811     /// </summary>
4812     /// <param name="string">The string to layout.</param>
4813     /// <param name="stringLength">The length of the string.</param>
4814     /// <param name="textFormat">The format to apply to the string.</param>
4815     /// <param name="maxWidth">Width of the layout box.</param>
4816     /// <param name="maxHeight">Height of the layout box.</param>
4817     /// <param name="textLayout">The resultant object.</param>
4818     /// <returns>
4819     /// Standard HRESULT error code.
4820     /// </returns>
4821     STDMETHOD(CreateTextLayout)(
4822         __in_ecount(stringLength) WCHAR const* string,
4823         UINT32 stringLength,
4824         IDWriteTextFormat* textFormat,
4825         FLOAT maxWidth,
4826         FLOAT maxHeight,
4827         __out IDWriteTextLayout** textLayout
4828         ) PURE;
4829 
4830     /// <summary>
4831     /// CreateGdiCompatibleTextLayout takes a string, format, and associated constraints
4832     /// and produces and object representing the result formatted for a particular display resolution
4833     /// and measuring method. The resulting text layout should only be used for the intended resolution,
4834     /// and for cases where text scalability is desired, CreateTextLayout should be used instead.
4835     /// </summary>
4836     /// <param name="string">The string to layout.</param>
4837     /// <param name="stringLength">The length of the string.</param>
4838     /// <param name="textFormat">The format to apply to the string.</param>
4839     /// <param name="layoutWidth">Width of the layout box.</param>
4840     /// <param name="layoutHeight">Height of the layout box.</param>
4841     /// <param name="pixelsPerDip">Number of physical pixels per DIP. For example, if rendering onto a 96 DPI device then pixelsPerDip
4842     /// is 1. If rendering onto a 120 DPI device then pixelsPerDip is 120/96.</param>
4843     /// <param name="transform">Optional transform applied to the glyphs and their positions. This transform is applied after the
4844     /// scaling specified the font size and pixelsPerDip.</param>
4845     /// <param name="useGdiNatural">
4846     /// When set to FALSE, instructs the text layout to use the same metrics as GDI aliased text.
4847     /// When set to TRUE, instructs the text layout to use the same metrics as text measured by GDI using a font
4848     /// created with CLEARTYPE_NATURAL_QUALITY.
4849     /// </param>
4850     /// <param name="textLayout">The resultant object.</param>
4851     /// <returns>
4852     /// Standard HRESULT error code.
4853     /// </returns>
4854     STDMETHOD(CreateGdiCompatibleTextLayout)(
4855         __in_ecount(stringLength) WCHAR const* string,
4856         UINT32 stringLength,
4857         IDWriteTextFormat* textFormat,
4858         FLOAT layoutWidth,
4859         FLOAT layoutHeight,
4860         FLOAT pixelsPerDip,
4861         __in_opt DWRITE_MATRIX const* transform,
4862         BOOL useGdiNatural,
4863         __out IDWriteTextLayout** textLayout
4864         ) PURE;
4865 
4866     /// <summary>
4867     /// The application may call this function to create an inline object for trimming, using an ellipsis as the omission sign.
4868     /// The ellipsis will be created using the current settings of the format, including base font, style, and any effects.
4869     /// Alternate omission signs can be created by the application by implementing IDWriteInlineObject.
4870     /// </summary>
4871     /// <param name="textFormat">Text format used as a template for the omission sign.</param>
4872     /// <param name="trimmingSign">Created omission sign.</param>
4873     /// <returns>
4874     /// Standard HRESULT error code.
4875     /// </returns>
4876     STDMETHOD(CreateEllipsisTrimmingSign)(
4877         IDWriteTextFormat* textFormat,
4878         __out IDWriteInlineObject** trimmingSign
4879         ) PURE;
4880 
4881     /// <summary>
4882     /// Return an interface to perform text analysis with.
4883     /// </summary>
4884     /// <param name="textAnalyzer">The resultant object.</param>
4885     /// <returns>
4886     /// Standard HRESULT error code.
4887     /// </returns>
4888     STDMETHOD(CreateTextAnalyzer)(
4889         __out IDWriteTextAnalyzer** textAnalyzer
4890         ) PURE;
4891 
4892     /// <summary>
4893     /// Creates a number substitution object using a locale name,
4894     /// substitution method, and whether to ignore user overrides (uses NLS
4895     /// defaults for the given culture instead).
4896     /// </summary>
4897     /// <param name="substitutionMethod">Method of number substitution to use.</param>
4898     /// <param name="localeName">Which locale to obtain the digits from.</param>
4899     /// <param name="ignoreUserOverride">Ignore the user's settings and use the locale defaults</param>
4900     /// <param name="numberSubstitution">Receives a pointer to the newly created object.</param>
4901     STDMETHOD(CreateNumberSubstitution)(
4902         __in DWRITE_NUMBER_SUBSTITUTION_METHOD substitutionMethod,
4903         __in_z WCHAR const* localeName,
4904         __in BOOL ignoreUserOverride,
4905         __out IDWriteNumberSubstitution** numberSubstitution
4906         ) PURE;
4907 
4908     /// <summary>
4909     /// Creates a glyph run analysis object, which encapsulates information
4910     /// used to render a glyph run.
4911     /// </summary>
4912     /// <param name="glyphRun">Structure specifying the properties of the glyph run.</param>
4913     /// <param name="pixelsPerDip">Number of physical pixels per DIP. For example, if rendering onto a 96 DPI bitmap then pixelsPerDip
4914     /// is 1. If rendering onto a 120 DPI bitmap then pixelsPerDip is 120/96.</param>
4915     /// <param name="transform">Optional transform applied to the glyphs and their positions. This transform is applied after the
4916     /// scaling specified the emSize and pixelsPerDip.</param>
4917     /// <param name="renderingMode">Specifies the rendering mode, which must be one of the raster rendering modes (i.e., not default
4918     /// and not outline).</param>
4919     /// <param name="measuringMode">Specifies the method to measure glyphs.</param>
4920     /// <param name="baselineOriginX">Horizontal position of the baseline origin, in DIPs.</param>
4921     /// <param name="baselineOriginY">Vertical position of the baseline origin, in DIPs.</param>
4922     /// <param name="glyphRunAnalysis">Receives a pointer to the newly created object.</param>
4923     /// <returns>
4924     /// Standard HRESULT error code.
4925     /// </returns>
4926     STDMETHOD(CreateGlyphRunAnalysis)(
4927         __in DWRITE_GLYPH_RUN const* glyphRun,
4928         FLOAT pixelsPerDip,
4929         __in_opt DWRITE_MATRIX const* transform,
4930         DWRITE_RENDERING_MODE renderingMode,
4931         DWRITE_MEASURING_MODE measuringMode,
4932         FLOAT baselineOriginX,
4933         FLOAT baselineOriginY,
4934         __out IDWriteGlyphRunAnalysis** glyphRunAnalysis
4935         ) PURE;
4936 
4937 }; // interface IDWriteFactory
4938 
4939 /// <summary>
4940 /// Creates a DirectWrite factory object that is used for subsequent creation of individual DirectWrite objects.
4941 /// </summary>
4942 /// <param name="factoryType">Identifies whether the factory object will be shared or isolated.</param>
4943 /// <param name="iid">Identifies the DirectWrite factory interface, such as __uuidof(IDWriteFactory).</param>
4944 /// <param name="factory">Receives the DirectWrite factory object.</param>
4945 /// <returns>
4946 /// Standard HRESULT error code.
4947 /// </returns>
4948 /// <remarks>
4949 /// Obtains DirectWrite factory object that is used for subsequent creation of individual DirectWrite classes.
4950 /// DirectWrite factory contains internal state such as font loader registration and cached font data.
4951 /// In most cases it is recommended to use the shared factory object, because it allows multiple components
4952 /// that use DirectWrite to share internal DirectWrite state and reduce memory usage.
4953 /// However, there are cases when it is desirable to reduce the impact of a component,
4954 /// such as a plug-in from an untrusted source, on the rest of the process by sandboxing and isolating it
4955 /// from the rest of the process components. In such cases, it is recommended to use an isolated factory for the sandboxed
4956 /// component.
4957 /// </remarks>
4958 EXTERN_C HRESULT DWRITE_EXPORT DWriteCreateFactory(
4959     __in DWRITE_FACTORY_TYPE factoryType,
4960     __in REFIID iid,
4961     __out IUnknown **factory
4962     );
4963 
4964 // Macros used to define DirectWrite error codes.
4965 #define FACILITY_DWRITE 0x898
4966 #define DWRITE_ERR_BASE 0x5000
4967 #define MAKE_DWRITE_HR(severity, code) MAKE_HRESULT(severity, FACILITY_DWRITE, (DWRITE_ERR_BASE + code))
4968 #define MAKE_DWRITE_HR_ERR(code) MAKE_DWRITE_HR(SEVERITY_ERROR, code)
4969 
4970 /// <summary>
4971 /// Indicates an error in an input file such as a font file.
4972 /// </summary>
4973 #define DWRITE_E_FILEFORMAT             MAKE_DWRITE_HR_ERR(0x000)
4974 
4975 /// <summary>
4976 /// Indicates an error originating in DirectWrite code, which is not expected to occur but is safe to recover from.
4977 /// </summary>
4978 #define DWRITE_E_UNEXPECTED             MAKE_DWRITE_HR_ERR(0x001)
4979 
4980 /// <summary>
4981 /// Indicates the specified font does not exist.
4982 /// </summary>
4983 #define DWRITE_E_NOFONT                 MAKE_DWRITE_HR_ERR(0x002)
4984 
4985 /// <summary>
4986 /// A font file could not be opened because the file, directory, network location, drive, or other storage
4987 /// location does not exist or is unavailable.
4988 /// </summary>
4989 #define DWRITE_E_FILENOTFOUND           MAKE_DWRITE_HR_ERR(0x003)
4990 
4991 /// <summary>
4992 /// A font file exists but could not be opened due to access denied, sharing violation, or similar error.
4993 /// </summary>
4994 #define DWRITE_E_FILEACCESS             MAKE_DWRITE_HR_ERR(0x004)
4995 
4996 /// <summary>
4997 /// A font collection is obsolete due to changes in the system.
4998 /// </summary>
4999 #define DWRITE_E_FONTCOLLECTIONOBSOLETE MAKE_DWRITE_HR_ERR(0x005)
5000 
5001 /// <summary>
5002 /// The given interface is already registered.
5003 /// </summary>
5004 #define DWRITE_E_ALREADYREGISTERED      MAKE_DWRITE_HR_ERR(0x006)
5005 
5006 #endif /* DWRITE_H_INCLUDED */
5007