0374694f74ceb294e22174b478f9491be542a241
[pdfium.git] / core / src / fxge / Microsoft SDK / include / DWrite.h
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     /// </