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