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