1 /**************************************************************************** 2 * 3 * freetype.h 4 * 5 * FreeType high-level API and common types (specification only). 6 * 7 * Copyright (C) 1996-2023 by 8 * David Turner, Robert Wilhelm, and Werner Lemberg. 9 * 10 * This file is part of the FreeType project, and may only be used, 11 * modified, and distributed under the terms of the FreeType project 12 * license, LICENSE.TXT. By continuing to use, modify, or distribute 13 * this file you indicate that you have read the license and 14 * understand and accept it fully. 15 * 16 */ 17 18 19 #ifndef FREETYPE_H_ 20 #define FREETYPE_H_ 21 22 23 #include <ft2build.h> 24 #include FT_CONFIG_CONFIG_H 25 #include <freetype/fttypes.h> 26 #include <freetype/fterrors.h> 27 28 29 FT_BEGIN_HEADER 30 31 32 33 /************************************************************************** 34 * 35 * @section: 36 * preamble 37 * 38 * @title: 39 * Preamble 40 * 41 * @abstract: 42 * What FreeType is and isn't 43 * 44 * @description: 45 * FreeType is a library that provides access to glyphs in font files. It 46 * scales the glyph images and their metrics to a requested size, and it 47 * rasterizes the glyph images to produce pixel or subpixel alpha coverage 48 * bitmaps. 49 * 50 * Note that FreeType is _not_ a text layout engine. You have to use 51 * higher-level libraries like HarfBuzz, Pango, or ICU for that. 52 * 53 * Note also that FreeType does _not_ perform alpha blending or 54 * compositing the resulting bitmaps or pixmaps by itself. Use your 55 * favourite graphics library (for example, Cairo or Skia) to further 56 * process FreeType's output. 57 * 58 */ 59 60 61 /************************************************************************** 62 * 63 * @section: 64 * header_inclusion 65 * 66 * @title: 67 * FreeType's header inclusion scheme 68 * 69 * @abstract: 70 * How client applications should include FreeType header files. 71 * 72 * @description: 73 * To be as flexible as possible (and for historical reasons), you must 74 * load file `ft2build.h` first before other header files, for example 75 * 76 * ``` 77 * #include <ft2build.h> 78 * 79 * #include <freetype/freetype.h> 80 * #include <freetype/ftoutln.h> 81 * ``` 82 */ 83 84 85 /************************************************************************** 86 * 87 * @section: 88 * user_allocation 89 * 90 * @title: 91 * User allocation 92 * 93 * @abstract: 94 * How client applications should allocate FreeType data structures. 95 * 96 * @description: 97 * FreeType assumes that structures allocated by the user and passed as 98 * arguments are zeroed out except for the actual data. In other words, 99 * it is recommended to use `calloc` (or variants of it) instead of 100 * `malloc` for allocation. 101 * 102 */ 103 104 105 /************************************************************************** 106 * 107 * @section: 108 * font_testing_macros 109 * 110 * @title: 111 * Font Testing Macros 112 * 113 * @abstract: 114 * Macros to test various properties of fonts. 115 * 116 * @description: 117 * Macros to test the most important font properties. 118 * 119 * It is recommended to use these high-level macros instead of directly 120 * testing the corresponding flags, which are scattered over various 121 * structures. 122 * 123 * @order: 124 * FT_HAS_HORIZONTAL 125 * FT_HAS_VERTICAL 126 * FT_HAS_KERNING 127 * FT_HAS_FIXED_SIZES 128 * FT_HAS_GLYPH_NAMES 129 * FT_HAS_COLOR 130 * FT_HAS_MULTIPLE_MASTERS 131 * FT_HAS_SVG 132 * FT_HAS_SBIX 133 * FT_HAS_SBIX_OVERLAY 134 * 135 * FT_IS_SFNT 136 * FT_IS_SCALABLE 137 * FT_IS_FIXED_WIDTH 138 * FT_IS_CID_KEYED 139 * FT_IS_TRICKY 140 * FT_IS_NAMED_INSTANCE 141 * FT_IS_VARIATION 142 * 143 */ 144 145 146 /************************************************************************** 147 * 148 * @section: 149 * library_setup 150 * 151 * @title: 152 * Library Setup 153 * 154 * @abstract: 155 * Functions to start and end the usage of the FreeType library. 156 * 157 * @description: 158 * Functions to start and end the usage of the FreeType library. 159 * 160 * Note that @FT_Library_Version and @FREETYPE_XXX are of limited use 161 * because even a new release of FreeType with only documentation 162 * changes increases the version number. 163 * 164 * @order: 165 * FT_Library 166 * FT_Init_FreeType 167 * FT_Done_FreeType 168 * 169 * FT_Library_Version 170 * FREETYPE_XXX 171 * 172 */ 173 174 175 /************************************************************************** 176 * 177 * @section: 178 * face_creation 179 * 180 * @title: 181 * Face Creation 182 * 183 * @abstract: 184 * Functions to manage fonts. 185 * 186 * @description: 187 * The functions and structures collected in this section operate on 188 * fonts globally. 189 * 190 * @order: 191 * FT_Face 192 * FT_FaceRec 193 * FT_FACE_FLAG_XXX 194 * FT_STYLE_FLAG_XXX 195 * 196 * FT_New_Face 197 * FT_Done_Face 198 * FT_Reference_Face 199 * FT_New_Memory_Face 200 * FT_Face_Properties 201 * FT_Open_Face 202 * FT_Open_Args 203 * FT_OPEN_XXX 204 * FT_Parameter 205 * FT_Attach_File 206 * FT_Attach_Stream 207 * 208 */ 209 210 211 /************************************************************************** 212 * 213 * @section: 214 * sizing_and_scaling 215 * 216 * @title: 217 * Sizing and Scaling 218 * 219 * @abstract: 220 * Functions to manage font sizes. 221 * 222 * @description: 223 * The functions and structures collected in this section are related to 224 * selecting and manipulating the size of a font globally. 225 * 226 * @order: 227 * FT_Size 228 * FT_SizeRec 229 * FT_Size_Metrics 230 * 231 * FT_Bitmap_Size 232 * 233 * FT_Set_Char_Size 234 * FT_Set_Pixel_Sizes 235 * FT_Request_Size 236 * FT_Select_Size 237 * FT_Size_Request_Type 238 * FT_Size_RequestRec 239 * FT_Size_Request 240 * 241 * FT_Set_Transform 242 * FT_Get_Transform 243 * 244 */ 245 246 247 /************************************************************************** 248 * 249 * @section: 250 * glyph_retrieval 251 * 252 * @title: 253 * Glyph Retrieval 254 * 255 * @abstract: 256 * Functions to manage glyphs. 257 * 258 * @description: 259 * The functions and structures collected in this section operate on 260 * single glyphs, of which @FT_Load_Glyph is most important. 261 * 262 * @order: 263 * FT_GlyphSlot 264 * FT_GlyphSlotRec 265 * FT_Glyph_Metrics 266 * 267 * FT_Load_Glyph 268 * FT_LOAD_XXX 269 * FT_LOAD_TARGET_MODE 270 * FT_LOAD_TARGET_XXX 271 * 272 * FT_Render_Glyph 273 * FT_Render_Mode 274 * FT_Get_Kerning 275 * FT_Kerning_Mode 276 * FT_Get_Track_Kerning 277 * 278 */ 279 280 281 /************************************************************************** 282 * 283 * @section: 284 * character_mapping 285 * 286 * @title: 287 * Character Mapping 288 * 289 * @abstract: 290 * Functions to manage character-to-glyph maps. 291 * 292 * @description: 293 * This section holds functions and structures that are related to 294 * mapping character input codes to glyph indices. 295 * 296 * Note that for many scripts the simplistic approach used by FreeType 297 * of mapping a single character to a single glyph is not valid or 298 * possible! In general, a higher-level library like HarfBuzz or ICU 299 * should be used for handling text strings. 300 * 301 * @order: 302 * FT_CharMap 303 * FT_CharMapRec 304 * FT_Encoding 305 * FT_ENC_TAG 306 * 307 * FT_Select_Charmap 308 * FT_Set_Charmap 309 * FT_Get_Charmap_Index 310 * 311 * FT_Get_Char_Index 312 * FT_Get_First_Char 313 * FT_Get_Next_Char 314 * FT_Load_Char 315 * 316 */ 317 318 319 /************************************************************************** 320 * 321 * @section: 322 * information_retrieval 323 * 324 * @title: 325 * Information Retrieval 326 * 327 * @abstract: 328 * Functions to retrieve font and glyph information. 329 * 330 * @description: 331 * Functions to retrieve font and glyph information. Only some very 332 * basic data is covered; see also the chapter on the format-specific 333 * API for more. 334 * 335 * 336 * @order: 337 * FT_Get_Name_Index 338 * FT_Get_Glyph_Name 339 * FT_Get_Postscript_Name 340 * FT_Get_FSType_Flags 341 * FT_FSTYPE_XXX 342 * FT_Get_SubGlyph_Info 343 * FT_SUBGLYPH_FLAG_XXX 344 * 345 */ 346 347 348 /************************************************************************** 349 * 350 * @section: 351 * other_api_data 352 * 353 * @title: 354 * Other API Data 355 * 356 * @abstract: 357 * Other structures, enumerations, and macros. 358 * 359 * @description: 360 * Other structures, enumerations, and macros. Deprecated functions are 361 * also listed here. 362 * 363 * @order: 364 * FT_Face_Internal 365 * FT_Size_Internal 366 * FT_Slot_Internal 367 * 368 * FT_SubGlyph 369 * 370 * FT_HAS_FAST_GLYPHS 371 * FT_Face_CheckTrueTypePatents 372 * FT_Face_SetUnpatentedHinting 373 * 374 */ 375 376 377 /*************************************************************************/ 378 /*************************************************************************/ 379 /* */ 380 /* B A S I C T Y P E S */ 381 /* */ 382 /*************************************************************************/ 383 /*************************************************************************/ 384 385 386 /************************************************************************** 387 * 388 * @section: 389 * glyph_retrieval 390 * 391 */ 392 393 /************************************************************************** 394 * 395 * @struct: 396 * FT_Glyph_Metrics 397 * 398 * @description: 399 * A structure to model the metrics of a single glyph. The values are 400 * expressed in 26.6 fractional pixel format; if the flag 401 * @FT_LOAD_NO_SCALE has been used while loading the glyph, values are 402 * expressed in font units instead. 403 * 404 * @fields: 405 * width :: 406 * The glyph's width. 407 * 408 * height :: 409 * The glyph's height. 410 * 411 * horiBearingX :: 412 * Left side bearing for horizontal layout. 413 * 414 * horiBearingY :: 415 * Top side bearing for horizontal layout. 416 * 417 * horiAdvance :: 418 * Advance width for horizontal layout. 419 * 420 * vertBearingX :: 421 * Left side bearing for vertical layout. 422 * 423 * vertBearingY :: 424 * Top side bearing for vertical layout. Larger positive values mean 425 * further below the vertical glyph origin. 426 * 427 * vertAdvance :: 428 * Advance height for vertical layout. Positive values mean the glyph 429 * has a positive advance downward. 430 * 431 * @note: 432 * If not disabled with @FT_LOAD_NO_HINTING, the values represent 433 * dimensions of the hinted glyph (in case hinting is applicable). 434 * 435 * Stroking a glyph with an outside border does not increase 436 * `horiAdvance` or `vertAdvance`; you have to manually adjust these 437 * values to account for the added width and height. 438 * 439 * FreeType doesn't use the 'VORG' table data for CFF fonts because it 440 * doesn't have an interface to quickly retrieve the glyph height. The 441 * y~coordinate of the vertical origin can be simply computed as 442 * `vertBearingY + height` after loading a glyph. 443 */ 444 typedef struct FT_Glyph_Metrics_ 445 { 446 FT_Pos width; 447 FT_Pos height; 448 449 FT_Pos horiBearingX; 450 FT_Pos horiBearingY; 451 FT_Pos horiAdvance; 452 453 FT_Pos vertBearingX; 454 FT_Pos vertBearingY; 455 FT_Pos vertAdvance; 456 457 } FT_Glyph_Metrics; 458 459 460 /************************************************************************** 461 * 462 * @section: 463 * sizing_and_scaling 464 * 465 */ 466 467 /************************************************************************** 468 * 469 * @struct: 470 * FT_Bitmap_Size 471 * 472 * @description: 473 * This structure models the metrics of a bitmap strike (i.e., a set of 474 * glyphs for a given point size and resolution) in a bitmap font. It is 475 * used for the `available_sizes` field of @FT_Face. 476 * 477 * @fields: 478 * height :: 479 * The vertical distance, in pixels, between two consecutive baselines. 480 * It is always positive. 481 * 482 * width :: 483 * The average width, in pixels, of all glyphs in the strike. 484 * 485 * size :: 486 * The nominal size of the strike in 26.6 fractional points. This 487 * field is not very useful. 488 * 489 * x_ppem :: 490 * The horizontal ppem (nominal width) in 26.6 fractional pixels. 491 * 492 * y_ppem :: 493 * The vertical ppem (nominal height) in 26.6 fractional pixels. 494 * 495 * @note: 496 * Windows FNT: 497 * The nominal size given in a FNT font is not reliable. If the driver 498 * finds it incorrect, it sets `size` to some calculated values, and 499 * `x_ppem` and `y_ppem` to the pixel width and height given in the 500 * font, respectively. 501 * 502 * TrueType embedded bitmaps: 503 * `size`, `width`, and `height` values are not contained in the bitmap 504 * strike itself. They are computed from the global font parameters. 505 */ 506 typedef struct FT_Bitmap_Size_ 507 { 508 FT_Short height; 509 FT_Short width; 510 511 FT_Pos size; 512 513 FT_Pos x_ppem; 514 FT_Pos y_ppem; 515 516 } FT_Bitmap_Size; 517 518 519 /*************************************************************************/ 520 /*************************************************************************/ 521 /* */ 522 /* O B J E C T C L A S S E S */ 523 /* */ 524 /*************************************************************************/ 525 /*************************************************************************/ 526 527 /************************************************************************** 528 * 529 * @section: 530 * library_setup 531 * 532 */ 533 534 /************************************************************************** 535 * 536 * @type: 537 * FT_Library 538 * 539 * @description: 540 * A handle to a FreeType library instance. Each 'library' is completely 541 * independent from the others; it is the 'root' of a set of objects like 542 * fonts, faces, sizes, etc. 543 * 544 * It also embeds a memory manager (see @FT_Memory), as well as a 545 * scan-line converter object (see @FT_Raster). 546 * 547 * [Since 2.5.6] In multi-threaded applications it is easiest to use one 548 * `FT_Library` object per thread. In case this is too cumbersome, a 549 * single `FT_Library` object across threads is possible also, as long as 550 * a mutex lock is used around @FT_New_Face and @FT_Done_Face. 551 * 552 * @note: 553 * Library objects are normally created by @FT_Init_FreeType, and 554 * destroyed with @FT_Done_FreeType. If you need reference-counting 555 * (cf. @FT_Reference_Library), use @FT_New_Library and @FT_Done_Library. 556 */ 557 typedef struct FT_LibraryRec_ *FT_Library; 558 559 560 /************************************************************************** 561 * 562 * @section: 563 * module_management 564 * 565 */ 566 567 /************************************************************************** 568 * 569 * @type: 570 * FT_Module 571 * 572 * @description: 573 * A handle to a given FreeType module object. A module can be a font 574 * driver, a renderer, or anything else that provides services to the 575 * former. 576 */ 577 typedef struct FT_ModuleRec_* FT_Module; 578 579 580 /************************************************************************** 581 * 582 * @type: 583 * FT_Driver 584 * 585 * @description: 586 * A handle to a given FreeType font driver object. A font driver is a 587 * module capable of creating faces from font files. 588 */ 589 typedef struct FT_DriverRec_* FT_Driver; 590 591 592 /************************************************************************** 593 * 594 * @type: 595 * FT_Renderer 596 * 597 * @description: 598 * A handle to a given FreeType renderer. A renderer is a module in 599 * charge of converting a glyph's outline image to a bitmap. It supports 600 * a single glyph image format, and one or more target surface depths. 601 */ 602 typedef struct FT_RendererRec_* FT_Renderer; 603 604 605 /************************************************************************** 606 * 607 * @section: 608 * face_creation 609 * 610 */ 611 612 /************************************************************************** 613 * 614 * @type: 615 * FT_Face 616 * 617 * @description: 618 * A handle to a typographic face object. A face object models a given 619 * typeface, in a given style. 620 * 621 * @note: 622 * A face object also owns a single @FT_GlyphSlot object, as well as one 623 * or more @FT_Size objects. 624 * 625 * Use @FT_New_Face or @FT_Open_Face to create a new face object from a 626 * given filepath or a custom input stream. 627 * 628 * Use @FT_Done_Face to destroy it (along with its slot and sizes). 629 * 630 * An `FT_Face` object can only be safely used from one thread at a time. 631 * Similarly, creation and destruction of `FT_Face` with the same 632 * @FT_Library object can only be done from one thread at a time. On the 633 * other hand, functions like @FT_Load_Glyph and its siblings are 634 * thread-safe and do not need the lock to be held as long as the same 635 * `FT_Face` object is not used from multiple threads at the same time. 636 * 637 * @also: 638 * See @FT_FaceRec for the publicly accessible fields of a given face 639 * object. 640 */ 641 typedef struct FT_FaceRec_* FT_Face; 642 643 644 /************************************************************************** 645 * 646 * @section: 647 * sizing_and_scaling 648 * 649 */ 650 651 /************************************************************************** 652 * 653 * @type: 654 * FT_Size 655 * 656 * @description: 657 * A handle to an object that models a face scaled to a given character 658 * size. 659 * 660 * @note: 661 * An @FT_Face has one _active_ `FT_Size` object that is used by 662 * functions like @FT_Load_Glyph to determine the scaling transformation 663 * that in turn is used to load and hint glyphs and metrics. 664 * 665 * A newly created `FT_Size` object contains only meaningless zero values. 666 * You must use @FT_Set_Char_Size, @FT_Set_Pixel_Sizes, @FT_Request_Size 667 * or even @FT_Select_Size to change the content (i.e., the scaling 668 * values) of the active `FT_Size`. Otherwise, the scaling and hinting 669 * will not be performed. 670 * 671 * You can use @FT_New_Size to create additional size objects for a given 672 * @FT_Face, but they won't be used by other functions until you activate 673 * it through @FT_Activate_Size. Only one size can be activated at any 674 * given time per face. 675 * 676 * @also: 677 * See @FT_SizeRec for the publicly accessible fields of a given size 678 * object. 679 */ 680 typedef struct FT_SizeRec_* FT_Size; 681 682 683 /************************************************************************** 684 * 685 * @section: 686 * glyph_retrieval 687 * 688 */ 689 690 /************************************************************************** 691 * 692 * @type: 693 * FT_GlyphSlot 694 * 695 * @description: 696 * A handle to a given 'glyph slot'. A slot is a container that can hold 697 * any of the glyphs contained in its parent face. 698 * 699 * In other words, each time you call @FT_Load_Glyph or @FT_Load_Char, 700 * the slot's content is erased by the new glyph data, i.e., the glyph's 701 * metrics, its image (bitmap or outline), and other control information. 702 * 703 * @also: 704 * See @FT_GlyphSlotRec for the publicly accessible glyph fields. 705 */ 706 typedef struct FT_GlyphSlotRec_* FT_GlyphSlot; 707 708 709 /************************************************************************** 710 * 711 * @section: 712 * character_mapping 713 * 714 */ 715 716 /************************************************************************** 717 * 718 * @type: 719 * FT_CharMap 720 * 721 * @description: 722 * A handle to a character map (usually abbreviated to 'charmap'). A 723 * charmap is used to translate character codes in a given encoding into 724 * glyph indexes for its parent's face. Some font formats may provide 725 * several charmaps per font. 726 * 727 * Each face object owns zero or more charmaps, but only one of them can 728 * be 'active', providing the data used by @FT_Get_Char_Index or 729 * @FT_Load_Char. 730 * 731 * The list of available charmaps in a face is available through the 732 * `face->num_charmaps` and `face->charmaps` fields of @FT_FaceRec. 733 * 734 * The currently active charmap is available as `face->charmap`. You 735 * should call @FT_Set_Charmap to change it. 736 * 737 * @note: 738 * When a new face is created (either through @FT_New_Face or 739 * @FT_Open_Face), the library looks for a Unicode charmap within the 740 * list and automatically activates it. If there is no Unicode charmap, 741 * FreeType doesn't set an 'active' charmap. 742 * 743 * @also: 744 * See @FT_CharMapRec for the publicly accessible fields of a given 745 * character map. 746 */ 747 typedef struct FT_CharMapRec_* FT_CharMap; 748 749 750 /************************************************************************** 751 * 752 * @macro: 753 * FT_ENC_TAG 754 * 755 * @description: 756 * This macro converts four-letter tags into an unsigned long. It is 757 * used to define 'encoding' identifiers (see @FT_Encoding). 758 * 759 * @note: 760 * Since many 16-bit compilers don't like 32-bit enumerations, you should 761 * redefine this macro in case of problems to something like this: 762 * 763 * ``` 764 * #define FT_ENC_TAG( value, a, b, c, d ) value 765 * ``` 766 * 767 * to get a simple enumeration without assigning special numbers. 768 */ 769 770 #ifndef FT_ENC_TAG 771 772 #define FT_ENC_TAG( value, a, b, c, d ) \ 773 value = ( ( FT_STATIC_BYTE_CAST( FT_UInt32, a ) << 24 ) | \ 774 ( FT_STATIC_BYTE_CAST( FT_UInt32, b ) << 16 ) | \ 775 ( FT_STATIC_BYTE_CAST( FT_UInt32, c ) << 8 ) | \ 776 FT_STATIC_BYTE_CAST( FT_UInt32, d ) ) 777 778 #endif /* FT_ENC_TAG */ 779 780 781 /************************************************************************** 782 * 783 * @enum: 784 * FT_Encoding 785 * 786 * @description: 787 * An enumeration to specify character sets supported by charmaps. Used 788 * in the @FT_Select_Charmap API function. 789 * 790 * @note: 791 * Despite the name, this enumeration lists specific character 792 * repertoires (i.e., charsets), and not text encoding methods (e.g., 793 * UTF-8, UTF-16, etc.). 794 * 795 * Other encodings might be defined in the future. 796 * 797 * @values: 798 * FT_ENCODING_NONE :: 799 * The encoding value~0 is reserved for all formats except BDF, PCF, 800 * and Windows FNT; see below for more information. 801 * 802 * FT_ENCODING_UNICODE :: 803 * The Unicode character set. This value covers all versions of the 804 * Unicode repertoire, including ASCII and Latin-1. Most fonts include 805 * a Unicode charmap, but not all of them. 806 * 807 * For example, if you want to access Unicode value U+1F028 (and the 808 * font contains it), use value 0x1F028 as the input value for 809 * @FT_Get_Char_Index. 810 * 811 * FT_ENCODING_MS_SYMBOL :: 812 * Microsoft Symbol encoding, used to encode mathematical symbols and 813 * wingdings. For more information, see 814 * 'https://www.microsoft.com/typography/otspec/recom.htm#non-standard-symbol-fonts', 815 * 'http://www.kostis.net/charsets/symbol.htm', and 816 * 'http://www.kostis.net/charsets/wingding.htm'. 817 * 818 * This encoding uses character codes from the PUA (Private Unicode 819 * Area) in the range U+F020-U+F0FF. 820 * 821 * FT_ENCODING_SJIS :: 822 * Shift JIS encoding for Japanese. More info at 823 * 'https://en.wikipedia.org/wiki/Shift_JIS'. See note on multi-byte 824 * encodings below. 825 * 826 * FT_ENCODING_PRC :: 827 * Corresponds to encoding systems mainly for Simplified Chinese as 828 * used in People's Republic of China (PRC). The encoding layout is 829 * based on GB~2312 and its supersets GBK and GB~18030. 830 * 831 * FT_ENCODING_BIG5 :: 832 * Corresponds to an encoding system for Traditional Chinese as used in 833 * Taiwan and Hong Kong. 834 * 835 * FT_ENCODING_WANSUNG :: 836 * Corresponds to the Korean encoding system known as Extended Wansung 837 * (MS Windows code page 949). For more information see 838 * 'https://www.unicode.org/Public/MAPPINGS/VENDORS/MICSFT/WindowsBestFit/bestfit949.txt'. 839 * 840 * FT_ENCODING_JOHAB :: 841 * The Korean standard character set (KS~C 5601-1992), which 842 * corresponds to MS Windows code page 1361. This character set 843 * includes all possible Hangul character combinations. 844 * 845 * FT_ENCODING_ADOBE_LATIN_1 :: 846 * Corresponds to a Latin-1 encoding as defined in a Type~1 PostScript 847 * font. It is limited to 256 character codes. 848 * 849 * FT_ENCODING_ADOBE_STANDARD :: 850 * Adobe Standard encoding, as found in Type~1, CFF, and OpenType/CFF 851 * fonts. It is limited to 256 character codes. 852 * 853 * FT_ENCODING_ADOBE_EXPERT :: 854 * Adobe Expert encoding, as found in Type~1, CFF, and OpenType/CFF 855 * fonts. It is limited to 256 character codes. 856 * 857 * FT_ENCODING_ADOBE_CUSTOM :: 858 * Corresponds to a custom encoding, as found in Type~1, CFF, and 859 * OpenType/CFF fonts. It is limited to 256 character codes. 860 * 861 * FT_ENCODING_APPLE_ROMAN :: 862 * Apple roman encoding. Many TrueType and OpenType fonts contain a 863 * charmap for this 8-bit encoding, since older versions of Mac OS are 864 * able to use it. 865 * 866 * FT_ENCODING_OLD_LATIN_2 :: 867 * This value is deprecated and was neither used nor reported by 868 * FreeType. Don't use or test for it. 869 * 870 * FT_ENCODING_MS_SJIS :: 871 * Same as FT_ENCODING_SJIS. Deprecated. 872 * 873 * FT_ENCODING_MS_GB2312 :: 874 * Same as FT_ENCODING_PRC. Deprecated. 875 * 876 * FT_ENCODING_MS_BIG5 :: 877 * Same as FT_ENCODING_BIG5. Deprecated. 878 * 879 * FT_ENCODING_MS_WANSUNG :: 880 * Same as FT_ENCODING_WANSUNG. Deprecated. 881 * 882 * FT_ENCODING_MS_JOHAB :: 883 * Same as FT_ENCODING_JOHAB. Deprecated. 884 * 885 * @note: 886 * When loading a font, FreeType makes a Unicode charmap active if 887 * possible (either if the font provides such a charmap, or if FreeType 888 * can synthesize one from PostScript glyph name dictionaries; in either 889 * case, the charmap is tagged with `FT_ENCODING_UNICODE`). If such a 890 * charmap is synthesized, it is placed at the first position of the 891 * charmap array. 892 * 893 * All other encodings are considered legacy and tagged only if 894 * explicitly defined in the font file. Otherwise, `FT_ENCODING_NONE` is 895 * used. 896 * 897 * `FT_ENCODING_NONE` is set by the BDF and PCF drivers if the charmap is 898 * neither Unicode nor ISO-8859-1 (otherwise it is set to 899 * `FT_ENCODING_UNICODE`). Use @FT_Get_BDF_Charset_ID to find out which 900 * encoding is really present. If, for example, the `cs_registry` field 901 * is 'KOI8' and the `cs_encoding` field is 'R', the font is encoded in 902 * KOI8-R. 903 * 904 * `FT_ENCODING_NONE` is always set (with a single exception) by the 905 * winfonts driver. Use @FT_Get_WinFNT_Header and examine the `charset` 906 * field of the @FT_WinFNT_HeaderRec structure to find out which encoding 907 * is really present. For example, @FT_WinFNT_ID_CP1251 (204) means 908 * Windows code page 1251 (for Russian). 909 * 910 * `FT_ENCODING_NONE` is set if `platform_id` is @TT_PLATFORM_MACINTOSH 911 * and `encoding_id` is not `TT_MAC_ID_ROMAN` (otherwise it is set to 912 * `FT_ENCODING_APPLE_ROMAN`). 913 * 914 * If `platform_id` is @TT_PLATFORM_MACINTOSH, use the function 915 * @FT_Get_CMap_Language_ID to query the Mac language ID that may be 916 * needed to be able to distinguish Apple encoding variants. See 917 * 918 * https://www.unicode.org/Public/MAPPINGS/VENDORS/APPLE/Readme.txt 919 * 920 * to get an idea how to do that. Basically, if the language ID is~0, 921 * don't use it, otherwise subtract 1 from the language ID. Then examine 922 * `encoding_id`. If, for example, `encoding_id` is `TT_MAC_ID_ROMAN` 923 * and the language ID (minus~1) is `TT_MAC_LANGID_GREEK`, it is the 924 * Greek encoding, not Roman. `TT_MAC_ID_ARABIC` with 925 * `TT_MAC_LANGID_FARSI` means the Farsi variant of the Arabic encoding. 926 */ 927 typedef enum FT_Encoding_ 928 { 929 FT_ENC_TAG( FT_ENCODING_NONE, 0, 0, 0, 0 ), 930 931 FT_ENC_TAG( FT_ENCODING_MS_SYMBOL, 's', 'y', 'm', 'b' ), 932 FT_ENC_TAG( FT_ENCODING_UNICODE, 'u', 'n', 'i', 'c' ), 933 934 FT_ENC_TAG( FT_ENCODING_SJIS, 's', 'j', 'i', 's' ), 935 FT_ENC_TAG( FT_ENCODING_PRC, 'g', 'b', ' ', ' ' ), 936 FT_ENC_TAG( FT_ENCODING_BIG5, 'b', 'i', 'g', '5' ), 937 FT_ENC_TAG( FT_ENCODING_WANSUNG, 'w', 'a', 'n', 's' ), 938 FT_ENC_TAG( FT_ENCODING_JOHAB, 'j', 'o', 'h', 'a' ), 939 940 /* for backward compatibility */ 941 FT_ENCODING_GB2312 = FT_ENCODING_PRC, 942 FT_ENCODING_MS_SJIS = FT_ENCODING_SJIS, 943 FT_ENCODING_MS_GB2312 = FT_ENCODING_PRC, 944 FT_ENCODING_MS_BIG5 = FT_ENCODING_BIG5, 945 FT_ENCODING_MS_WANSUNG = FT_ENCODING_WANSUNG, 946 FT_ENCODING_MS_JOHAB = FT_ENCODING_JOHAB, 947 948 FT_ENC_TAG( FT_ENCODING_ADOBE_STANDARD, 'A', 'D', 'O', 'B' ), 949 FT_ENC_TAG( FT_ENCODING_ADOBE_EXPERT, 'A', 'D', 'B', 'E' ), 950 FT_ENC_TAG( FT_ENCODING_ADOBE_CUSTOM, 'A', 'D', 'B', 'C' ), 951 FT_ENC_TAG( FT_ENCODING_ADOBE_LATIN_1, 'l', 'a', 't', '1' ), 952 953 FT_ENC_TAG( FT_ENCODING_OLD_LATIN_2, 'l', 'a', 't', '2' ), 954 955 FT_ENC_TAG( FT_ENCODING_APPLE_ROMAN, 'a', 'r', 'm', 'n' ) 956 957 } FT_Encoding; 958 959 960 /* these constants are deprecated; use the corresponding `FT_Encoding` */ 961 /* values instead */ 962 #define ft_encoding_none FT_ENCODING_NONE 963 #define ft_encoding_unicode FT_ENCODING_UNICODE 964 #define ft_encoding_symbol FT_ENCODING_MS_SYMBOL 965 #define ft_encoding_latin_1 FT_ENCODING_ADOBE_LATIN_1 966 #define ft_encoding_latin_2 FT_ENCODING_OLD_LATIN_2 967 #define ft_encoding_sjis FT_ENCODING_SJIS 968 #define ft_encoding_gb2312 FT_ENCODING_PRC 969 #define ft_encoding_big5 FT_ENCODING_BIG5 970 #define ft_encoding_wansung FT_ENCODING_WANSUNG 971 #define ft_encoding_johab FT_ENCODING_JOHAB 972 973 #define ft_encoding_adobe_standard FT_ENCODING_ADOBE_STANDARD 974 #define ft_encoding_adobe_expert FT_ENCODING_ADOBE_EXPERT 975 #define ft_encoding_adobe_custom FT_ENCODING_ADOBE_CUSTOM 976 #define ft_encoding_apple_roman FT_ENCODING_APPLE_ROMAN 977 978 979 /************************************************************************** 980 * 981 * @struct: 982 * FT_CharMapRec 983 * 984 * @description: 985 * The base charmap structure. 986 * 987 * @fields: 988 * face :: 989 * A handle to the parent face object. 990 * 991 * encoding :: 992 * An @FT_Encoding tag identifying the charmap. Use this with 993 * @FT_Select_Charmap. 994 * 995 * platform_id :: 996 * An ID number describing the platform for the following encoding ID. 997 * This comes directly from the TrueType specification and gets 998 * emulated for other formats. 999 * 1000 * encoding_id :: 1001 * A platform-specific encoding number. This also comes from the 1002 * TrueType specification and gets emulated similarly. 1003 */ 1004 typedef struct FT_CharMapRec_ 1005 { 1006 FT_Face face; 1007 FT_Encoding encoding; 1008 FT_UShort platform_id; 1009 FT_UShort encoding_id; 1010 1011 } FT_CharMapRec; 1012 1013 1014 /*************************************************************************/ 1015 /*************************************************************************/ 1016 /* */ 1017 /* B A S E O B J E C T C L A S S E S */ 1018 /* */ 1019 /*************************************************************************/ 1020 /*************************************************************************/ 1021 1022 1023 /************************************************************************** 1024 * 1025 * @section: 1026 * other_api_data 1027 * 1028 */ 1029 1030 /************************************************************************** 1031 * 1032 * @type: 1033 * FT_Face_Internal 1034 * 1035 * @description: 1036 * An opaque handle to an `FT_Face_InternalRec` structure that models the 1037 * private data of a given @FT_Face object. 1038 * 1039 * This structure might change between releases of FreeType~2 and is not 1040 * generally available to client applications. 1041 */ 1042 typedef struct FT_Face_InternalRec_* FT_Face_Internal; 1043 1044 1045 /************************************************************************** 1046 * 1047 * @section: 1048 * face_creation 1049 * 1050 */ 1051 1052 /************************************************************************** 1053 * 1054 * @struct: 1055 * FT_FaceRec 1056 * 1057 * @description: 1058 * FreeType root face class structure. A face object models a typeface 1059 * in a font file. 1060 * 1061 * @fields: 1062 * num_faces :: 1063 * The number of faces in the font file. Some font formats can have 1064 * multiple faces in a single font file. 1065 * 1066 * face_index :: 1067 * This field holds two different values. Bits 0-15 are the index of 1068 * the face in the font file (starting with value~0). They are set 1069 * to~0 if there is only one face in the font file. 1070 * 1071 * [Since 2.6.1] Bits 16-30 are relevant to GX and OpenType variation 1072 * fonts only, holding the named instance index for the current face 1073 * index (starting with value~1; value~0 indicates font access without 1074 * a named instance). For non-variation fonts, bits 16-30 are ignored. 1075 * If we have the third named instance of face~4, say, `face_index` is 1076 * set to 0x00030004. 1077 * 1078 * Bit 31 is always zero (that is, `face_index` is always a positive 1079 * value). 1080 * 1081 * [Since 2.9] Changing the design coordinates with 1082 * @FT_Set_Var_Design_Coordinates or @FT_Set_Var_Blend_Coordinates does 1083 * not influence the named instance index value (only 1084 * @FT_Set_Named_Instance does that). 1085 * 1086 * face_flags :: 1087 * A set of bit flags that give important information about the face; 1088 * see @FT_FACE_FLAG_XXX for the details. 1089 * 1090 * style_flags :: 1091 * The lower 16~bits contain a set of bit flags indicating the style of 1092 * the face; see @FT_STYLE_FLAG_XXX for the details. 1093 * 1094 * [Since 2.6.1] Bits 16-30 hold the number of named instances 1095 * available for the current face if we have a GX or OpenType variation 1096 * (sub)font. Bit 31 is always zero (that is, `style_flags` is always 1097 * a positive value). Note that a variation font has always at least 1098 * one named instance, namely the default instance. 1099 * 1100 * num_glyphs :: 1101 * The number of glyphs in the face. If the face is scalable and has 1102 * sbits (see `num_fixed_sizes`), it is set to the number of outline 1103 * glyphs. 1104 * 1105 * For CID-keyed fonts (not in an SFNT wrapper) this value gives the 1106 * highest CID used in the font. 1107 * 1108 * family_name :: 1109 * The face's family name. This is an ASCII string, usually in 1110 * English, that describes the typeface's family (like 'Times New 1111 * Roman', 'Bodoni', 'Garamond', etc). This is a least common 1112 * denominator used to list fonts. Some formats (TrueType & OpenType) 1113 * provide localized and Unicode versions of this string. Applications 1114 * should use the format-specific interface to access them. Can be 1115 * `NULL` (e.g., in fonts embedded in a PDF file). 1116 * 1117 * In case the font doesn't provide a specific family name entry, 1118 * FreeType tries to synthesize one, deriving it from other name 1119 * entries. 1120 * 1121 * style_name :: 1122 * The face's style name. This is an ASCII string, usually in English, 1123 * that describes the typeface's style (like 'Italic', 'Bold', 1124 * 'Condensed', etc). Not all font formats provide a style name, so 1125 * this field is optional, and can be set to `NULL`. As for 1126 * `family_name`, some formats provide localized and Unicode versions 1127 * of this string. Applications should use the format-specific 1128 * interface to access them. 1129 * 1130 * num_fixed_sizes :: 1131 * The number of bitmap strikes in the face. Even if the face is 1132 * scalable, there might still be bitmap strikes, which are called 1133 * 'sbits' in that case. 1134 * 1135 * available_sizes :: 1136 * An array of @FT_Bitmap_Size for all bitmap strikes in the face. It 1137 * is set to `NULL` if there is no bitmap strike. 1138 * 1139 * Note that FreeType tries to sanitize the strike data since they are 1140 * sometimes sloppy or incorrect, but this can easily fail. 1141 * 1142 * num_charmaps :: 1143 * The number of charmaps in the face. 1144 * 1145 * charmaps :: 1146 * An array of the charmaps of the face. 1147 * 1148 * generic :: 1149 * A field reserved for client uses. See the @FT_Generic type 1150 * description. 1151 * 1152 * bbox :: 1153 * The font bounding box. Coordinates are expressed in font units (see 1154 * `units_per_EM`). The box is large enough to contain any glyph from 1155 * the font. Thus, `bbox.yMax` can be seen as the 'maximum ascender', 1156 * and `bbox.yMin` as the 'minimum descender'. Only relevant for 1157 * scalable formats. 1158 * 1159 * Note that the bounding box might be off by (at least) one pixel for 1160 * hinted fonts. See @FT_Size_Metrics for further discussion. 1161 * 1162 * Note that the bounding box does not vary in OpenType variation fonts 1163 * and should only be used in relation to the default instance. 1164 * 1165 * units_per_EM :: 1166 * The number of font units per EM square for this face. This is 1167 * typically 2048 for TrueType fonts, and 1000 for Type~1 fonts. Only 1168 * relevant for scalable formats. 1169 * 1170 * ascender :: 1171 * The typographic ascender of the face, expressed in font units. For 1172 * font formats not having this information, it is set to `bbox.yMax`. 1173 * Only relevant for scalable formats. 1174 * 1175 * descender :: 1176 * The typographic descender of the face, expressed in font units. For 1177 * font formats not having this information, it is set to `bbox.yMin`. 1178 * Note that this field is negative for values below the baseline. 1179 * Only relevant for scalable formats. 1180 * 1181 * height :: 1182 * This value is the vertical distance between two consecutive 1183 * baselines, expressed in font units. It is always positive. Only 1184 * relevant for scalable formats. 1185 * 1186 * If you want the global glyph height, use `ascender - descender`. 1187 * 1188 * max_advance_width :: 1189 * The maximum advance width, in font units, for all glyphs in this 1190 * face. This can be used to make word wrapping computations faster. 1191 * Only relevant for scalable formats. 1192 * 1193 * max_advance_height :: 1194 * The maximum advance height, in font units, for all glyphs in this 1195 * face. This is only relevant for vertical layouts, and is set to 1196 * `height` for fonts that do not provide vertical metrics. Only 1197 * relevant for scalable formats. 1198 * 1199 * underline_position :: 1200 * The position, in font units, of the underline line for this face. 1201 * It is the center of the underlining stem. Only relevant for 1202 * scalable formats. 1203 * 1204 * underline_thickness :: 1205 * The thickness, in font units, of the underline for this face. Only 1206 * relevant for scalable formats. 1207 * 1208 * glyph :: 1209 * The face's associated glyph slot(s). 1210 * 1211 * size :: 1212 * The current active size for this face. 1213 * 1214 * charmap :: 1215 * The current active charmap for this face. 1216 * 1217 * @note: 1218 * Fields may be changed after a call to @FT_Attach_File or 1219 * @FT_Attach_Stream. 1220 * 1221 * For an OpenType variation font, the values of the following fields can 1222 * change after a call to @FT_Set_Var_Design_Coordinates (and friends) if 1223 * the font contains an 'MVAR' table: `ascender`, `descender`, `height`, 1224 * `underline_position`, and `underline_thickness`. 1225 * 1226 * Especially for TrueType fonts see also the documentation for 1227 * @FT_Size_Metrics. 1228 */ 1229 typedef struct FT_FaceRec_ 1230 { 1231 FT_Long num_faces; 1232 FT_Long face_index; 1233 1234 FT_Long face_flags; 1235 FT_Long style_flags; 1236 1237 FT_Long num_glyphs; 1238 1239 FT_String* family_name; 1240 FT_String* style_name; 1241 1242 FT_Int num_fixed_sizes; 1243 FT_Bitmap_Size* available_sizes; 1244 1245 FT_Int num_charmaps; 1246 FT_CharMap* charmaps; 1247 1248 FT_Generic generic; 1249 1250 /* The following member variables (down to `underline_thickness`) */ 1251 /* are only relevant to scalable outlines; cf. @FT_Bitmap_Size */ 1252 /* for bitmap fonts. */ 1253 FT_BBox bbox; 1254 1255 FT_UShort units_per_EM; 1256 FT_Short ascender; 1257 FT_Short descender; 1258 FT_Short height; 1259 1260 FT_Short max_advance_width; 1261 FT_Short max_advance_height; 1262 1263 FT_Short underline_position; 1264 FT_Short underline_thickness; 1265 1266 FT_GlyphSlot glyph; 1267 FT_Size size; 1268 FT_CharMap charmap; 1269 1270 /* private fields, internal to FreeType */ 1271 1272 FT_Driver driver; 1273 FT_Memory memory; 1274 FT_Stream stream; 1275 1276 FT_ListRec sizes_list; 1277 1278 FT_Generic autohint; /* face-specific auto-hinter data */ 1279 void* extensions; /* unused */ 1280 1281 FT_Face_Internal internal; 1282 1283 } FT_FaceRec; 1284 1285 1286 /************************************************************************** 1287 * 1288 * @enum: 1289 * FT_FACE_FLAG_XXX 1290 * 1291 * @description: 1292 * A list of bit flags used in the `face_flags` field of the @FT_FaceRec 1293 * structure. They inform client applications of properties of the 1294 * corresponding face. 1295 * 1296 * @values: 1297 * FT_FACE_FLAG_SCALABLE :: 1298 * The face contains outline glyphs. Note that a face can contain 1299 * bitmap strikes also, i.e., a face can have both this flag and 1300 * @FT_FACE_FLAG_FIXED_SIZES set. 1301 * 1302 * FT_FACE_FLAG_FIXED_SIZES :: 1303 * The face contains bitmap strikes. See also the `num_fixed_sizes` 1304 * and `available_sizes` fields of @FT_FaceRec. 1305 * 1306 * FT_FACE_FLAG_FIXED_WIDTH :: 1307 * The face contains fixed-width characters (like Courier, Lucida, 1308 * MonoType, etc.). 1309 * 1310 * FT_FACE_FLAG_SFNT :: 1311 * The face uses the SFNT storage scheme. For now, this means TrueType 1312 * and OpenType. 1313 * 1314 * FT_FACE_FLAG_HORIZONTAL :: 1315 * The face contains horizontal glyph metrics. This should be set for 1316 * all common formats. 1317 * 1318 * FT_FACE_FLAG_VERTICAL :: 1319 * The face contains vertical glyph metrics. This is only available in 1320 * some formats, not all of them. 1321 * 1322 * FT_FACE_FLAG_KERNING :: 1323 * The face contains kerning information. If set, the kerning distance 1324 * can be retrieved using the function @FT_Get_Kerning. Otherwise the 1325 * function always returns the vector (0,0). Note that FreeType 1326 * doesn't handle kerning data from the SFNT 'GPOS' table (as present 1327 * in many OpenType fonts). 1328 * 1329 * FT_FACE_FLAG_FAST_GLYPHS :: 1330 * THIS FLAG IS DEPRECATED. DO NOT USE OR TEST IT. 1331 * 1332 * FT_FACE_FLAG_MULTIPLE_MASTERS :: 1333 * The face contains multiple masters and is capable of interpolating 1334 * between them. Supported formats are Adobe MM, TrueType GX, and 1335 * OpenType variation fonts. 1336 * 1337 * See section @multiple_masters for API details. 1338 * 1339 * FT_FACE_FLAG_GLYPH_NAMES :: 1340 * The face contains glyph names, which can be retrieved using 1341 * @FT_Get_Glyph_Name. Note that some TrueType fonts contain broken 1342 * glyph name tables. Use the function @FT_Has_PS_Glyph_Names when 1343 * needed. 1344 * 1345 * FT_FACE_FLAG_EXTERNAL_STREAM :: 1346 * Used internally by FreeType to indicate that a face's stream was 1347 * provided by the client application and should not be destroyed when 1348 * @FT_Done_Face is called. Don't read or test this flag. 1349 * 1350 * FT_FACE_FLAG_HINTER :: 1351 * The font driver has a hinting machine of its own. For example, with 1352 * TrueType fonts, it makes sense to use data from the SFNT 'gasp' 1353 * table only if the native TrueType hinting engine (with the bytecode 1354 * interpreter) is available and active. 1355 * 1356 * FT_FACE_FLAG_CID_KEYED :: 1357 * The face is CID-keyed. In that case, the face is not accessed by 1358 * glyph indices but by CID values. For subsetted CID-keyed fonts this 1359 * has the consequence that not all index values are a valid argument 1360 * to @FT_Load_Glyph. Only the CID values for which corresponding 1361 * glyphs in the subsetted font exist make `FT_Load_Glyph` return 1362 * successfully; in all other cases you get an 1363 * `FT_Err_Invalid_Argument` error. 1364 * 1365 * Note that CID-keyed fonts that are in an SFNT wrapper (that is, all 1366 * OpenType/CFF fonts) don't have this flag set since the glyphs are 1367 * accessed in the normal way (using contiguous indices); the 1368 * 'CID-ness' isn't visible to the application. 1369 * 1370 * FT_FACE_FLAG_TRICKY :: 1371 * The face is 'tricky', that is, it always needs the font format's 1372 * native hinting engine to get a reasonable result. A typical example 1373 * is the old Chinese font `mingli.ttf` (but not `mingliu.ttc`) that 1374 * uses TrueType bytecode instructions to move and scale all of its 1375 * subglyphs. 1376 * 1377 * It is not possible to auto-hint such fonts using 1378 * @FT_LOAD_FORCE_AUTOHINT; it will also ignore @FT_LOAD_NO_HINTING. 1379 * You have to set both @FT_LOAD_NO_HINTING and @FT_LOAD_NO_AUTOHINT to 1380 * really disable hinting; however, you probably never want this except 1381 * for demonstration purposes. 1382 * 1383 * Currently, there are about a dozen TrueType fonts in the list of 1384 * tricky fonts; they are hard-coded in file `ttobjs.c`. 1385 * 1386 * FT_FACE_FLAG_COLOR :: 1387 * [Since 2.5.1] The face has color glyph tables. See @FT_LOAD_COLOR 1388 * for more information. 1389 * 1390 * FT_FACE_FLAG_VARIATION :: 1391 * [Since 2.9] Set if the current face (or named instance) has been 1392 * altered with @FT_Set_MM_Design_Coordinates, 1393 * @FT_Set_Var_Design_Coordinates, @FT_Set_Var_Blend_Coordinates, or 1394 * @FT_Set_MM_WeightVector to select a non-default instance. 1395 * 1396 * FT_FACE_FLAG_SVG :: 1397 * [Since 2.12] The face has an 'SVG~' OpenType table. 1398 * 1399 * FT_FACE_FLAG_SBIX :: 1400 * [Since 2.12] The face has an 'sbix' OpenType table *and* outlines. 1401 * For such fonts, @FT_FACE_FLAG_SCALABLE is not set by default to 1402 * retain backward compatibility. 1403 * 1404 * FT_FACE_FLAG_SBIX_OVERLAY :: 1405 * [Since 2.12] The face has an 'sbix' OpenType table where outlines 1406 * should be drawn on top of bitmap strikes. 1407 * 1408 */ 1409 #define FT_FACE_FLAG_SCALABLE ( 1L << 0 ) 1410 #define FT_FACE_FLAG_FIXED_SIZES ( 1L << 1 ) 1411 #define FT_FACE_FLAG_FIXED_WIDTH ( 1L << 2 ) 1412 #define FT_FACE_FLAG_SFNT ( 1L << 3 ) 1413 #define FT_FACE_FLAG_HORIZONTAL ( 1L << 4 ) 1414 #define FT_FACE_FLAG_VERTICAL ( 1L << 5 ) 1415 #define FT_FACE_FLAG_KERNING ( 1L << 6 ) 1416 #define FT_FACE_FLAG_FAST_GLYPHS ( 1L << 7 ) 1417 #define FT_FACE_FLAG_MULTIPLE_MASTERS ( 1L << 8 ) 1418 #define FT_FACE_FLAG_GLYPH_NAMES ( 1L << 9 ) 1419 #define FT_FACE_FLAG_EXTERNAL_STREAM ( 1L << 10 ) 1420 #define FT_FACE_FLAG_HINTER ( 1L << 11 ) 1421 #define FT_FACE_FLAG_CID_KEYED ( 1L << 12 ) 1422 #define FT_FACE_FLAG_TRICKY ( 1L << 13 ) 1423 #define FT_FACE_FLAG_COLOR ( 1L << 14 ) 1424 #define FT_FACE_FLAG_VARIATION ( 1L << 15 ) 1425 #define FT_FACE_FLAG_SVG ( 1L << 16 ) 1426 #define FT_FACE_FLAG_SBIX ( 1L << 17 ) 1427 #define FT_FACE_FLAG_SBIX_OVERLAY ( 1L << 18 ) 1428 1429 1430 /************************************************************************** 1431 * 1432 * @section: 1433 * font_testing_macros 1434 * 1435 */ 1436 1437 /************************************************************************** 1438 * 1439 * @macro: 1440 * FT_HAS_HORIZONTAL 1441 * 1442 * @description: 1443 * A macro that returns true whenever a face object contains horizontal 1444 * metrics (this is true for all font formats though). 1445 * 1446 * @also: 1447 * @FT_HAS_VERTICAL can be used to check for vertical metrics. 1448 * 1449 */ 1450 #define FT_HAS_HORIZONTAL( face ) \ 1451 ( !!( (face)->face_flags & FT_FACE_FLAG_HORIZONTAL ) ) 1452 1453 1454 /************************************************************************** 1455 * 1456 * @macro: 1457 * FT_HAS_VERTICAL 1458 * 1459 * @description: 1460 * A macro that returns true whenever a face object contains real 1461 * vertical metrics (and not only synthesized ones). 1462 * 1463 */ 1464 #define FT_HAS_VERTICAL( face ) \ 1465 ( !!( (face)->face_flags & FT_FACE_FLAG_VERTICAL ) ) 1466 1467 1468 /************************************************************************** 1469 * 1470 * @macro: 1471 * FT_HAS_KERNING 1472 * 1473 * @description: 1474 * A macro that returns true whenever a face object contains kerning data 1475 * that can be accessed with @FT_Get_Kerning. 1476 * 1477 */ 1478 #define FT_HAS_KERNING( face ) \ 1479 ( !!( (face)->face_flags & FT_FACE_FLAG_KERNING ) ) 1480 1481 1482 /************************************************************************** 1483 * 1484 * @macro: 1485 * FT_IS_SCALABLE 1486 * 1487 * @description: 1488 * A macro that returns true whenever a face object contains a scalable 1489 * font face (true for TrueType, Type~1, Type~42, CID, OpenType/CFF, and 1490 * PFR font formats). 1491 * 1492 */ 1493 #define FT_IS_SCALABLE( face ) \ 1494 ( !!( (face)->face_flags & FT_FACE_FLAG_SCALABLE ) ) 1495 1496 1497 /************************************************************************** 1498 * 1499 * @macro: 1500 * FT_IS_SFNT 1501 * 1502 * @description: 1503 * A macro that returns true whenever a face object contains a font whose 1504 * format is based on the SFNT storage scheme. This usually means: 1505 * TrueType fonts, OpenType fonts, as well as SFNT-based embedded bitmap 1506 * fonts. 1507 * 1508 * If this macro is true, all functions defined in @FT_SFNT_NAMES_H and 1509 * @FT_TRUETYPE_TABLES_H are available. 1510 * 1511 */ 1512 #define FT_IS_SFNT( face ) \ 1513 ( !!( (face)->face_flags & FT_FACE_FLAG_SFNT ) ) 1514 1515 1516 /************************************************************************** 1517 * 1518 * @macro: 1519 * FT_IS_FIXED_WIDTH 1520 * 1521 * @description: 1522 * A macro that returns true whenever a face object contains a font face 1523 * that contains fixed-width (or 'monospace', 'fixed-pitch', etc.) 1524 * glyphs. 1525 * 1526 */ 1527 #define FT_IS_FIXED_WIDTH( face ) \ 1528 ( !!( (face)->face_flags & FT_FACE_FLAG_FIXED_WIDTH ) ) 1529 1530 1531 /************************************************************************** 1532 * 1533 * @macro: 1534 * FT_HAS_FIXED_SIZES 1535 * 1536 * @description: 1537 * A macro that returns true whenever a face object contains some 1538 * embedded bitmaps. See the `available_sizes` field of the @FT_FaceRec 1539 * structure. 1540 * 1541 */ 1542 #define FT_HAS_FIXED_SIZES( face ) \ 1543 ( !!( (face)->face_flags & FT_FACE_FLAG_FIXED_SIZES ) ) 1544 1545 1546 /************************************************************************** 1547 * 1548 * @section: 1549 * other_api_data 1550 * 1551 */ 1552 1553 /************************************************************************** 1554 * 1555 * @macro: 1556 * FT_HAS_FAST_GLYPHS 1557 * 1558 * @description: 1559 * Deprecated. 1560 * 1561 */ 1562 #define FT_HAS_FAST_GLYPHS( face ) 0 1563 1564 1565 /************************************************************************** 1566 * 1567 * @section: 1568 * font_testing_macros 1569 * 1570 */ 1571 1572 /************************************************************************** 1573 * 1574 * @macro: 1575 * FT_HAS_GLYPH_NAMES 1576 * 1577 * @description: 1578 * A macro that returns true whenever a face object contains some glyph 1579 * names that can be accessed through @FT_Get_Glyph_Name. 1580 * 1581 */ 1582 #define FT_HAS_GLYPH_NAMES( face ) \ 1583 ( !!( (face)->face_flags & FT_FACE_FLAG_GLYPH_NAMES ) ) 1584 1585 1586 /************************************************************************** 1587 * 1588 * @macro: 1589 * FT_HAS_MULTIPLE_MASTERS 1590 * 1591 * @description: 1592 * A macro that returns true whenever a face object contains some 1593 * multiple masters. The functions provided by @FT_MULTIPLE_MASTERS_H 1594 * are then available to choose the exact design you want. 1595 * 1596 */ 1597 #define FT_HAS_MULTIPLE_MASTERS( face ) \ 1598 ( !!( (face)->face_flags & FT_FACE_FLAG_MULTIPLE_MASTERS ) ) 1599 1600 1601 /************************************************************************** 1602 * 1603 * @macro: 1604 * FT_IS_NAMED_INSTANCE 1605 * 1606 * @description: 1607 * A macro that returns true whenever a face object is a named instance 1608 * of a GX or OpenType variation font. 1609 * 1610 * [Since 2.9] Changing the design coordinates with 1611 * @FT_Set_Var_Design_Coordinates or @FT_Set_Var_Blend_Coordinates does 1612 * not influence the return value of this macro (only 1613 * @FT_Set_Named_Instance does that). 1614 * 1615 * @since: 1616 * 2.7 1617 * 1618 */ 1619 #define FT_IS_NAMED_INSTANCE( face ) \ 1620 ( !!( (face)->face_index & 0x7FFF0000L ) ) 1621 1622 1623 /************************************************************************** 1624 * 1625 * @macro: 1626 * FT_IS_VARIATION 1627 * 1628 * @description: 1629 * A macro that returns true whenever a face object has been altered by 1630 * @FT_Set_MM_Design_Coordinates, @FT_Set_Var_Design_Coordinates, 1631 * @FT_Set_Var_Blend_Coordinates, or @FT_Set_MM_WeightVector. 1632 * 1633 * @since: 1634 * 2.9 1635 * 1636 */ 1637 #define FT_IS_VARIATION( face ) \ 1638 ( !!( (face)->face_flags & FT_FACE_FLAG_VARIATION ) ) 1639 1640 1641 /************************************************************************** 1642 * 1643 * @macro: 1644 * FT_IS_CID_KEYED 1645 * 1646 * @description: 1647 * A macro that returns true whenever a face object contains a CID-keyed 1648 * font. See the discussion of @FT_FACE_FLAG_CID_KEYED for more details. 1649 * 1650 * If this macro is true, all functions defined in @FT_CID_H are 1651 * available. 1652 * 1653 */ 1654 #define FT_IS_CID_KEYED( face ) \ 1655 ( !!( (face)->face_flags & FT_FACE_FLAG_CID_KEYED ) ) 1656 1657 1658 /************************************************************************** 1659 * 1660 * @macro: 1661 * FT_IS_TRICKY 1662 * 1663 * @description: 1664 * A macro that returns true whenever a face represents a 'tricky' font. 1665 * See the discussion of @FT_FACE_FLAG_TRICKY for more details. 1666 * 1667 */ 1668 #define FT_IS_TRICKY( face ) \ 1669 ( !!( (face)->face_flags & FT_FACE_FLAG_TRICKY ) ) 1670 1671 1672 /************************************************************************** 1673 * 1674 * @macro: 1675 * FT_HAS_COLOR 1676 * 1677 * @description: 1678 * A macro that returns true whenever a face object contains tables for 1679 * color glyphs. 1680 * 1681 * @since: 1682 * 2.5.1 1683 * 1684 */ 1685 #define FT_HAS_COLOR( face ) \ 1686 ( !!( (face)->face_flags & FT_FACE_FLAG_COLOR ) ) 1687 1688 1689 /************************************************************************** 1690 * 1691 * @macro: 1692 * FT_HAS_SVG 1693 * 1694 * @description: 1695 * A macro that returns true whenever a face object contains an 'SVG~' 1696 * OpenType table. 1697 * 1698 * @since: 1699 * 2.12 1700 */ 1701 #define FT_HAS_SVG( face ) \ 1702 ( !!( (face)->face_flags & FT_FACE_FLAG_SVG ) ) 1703 1704 1705 /************************************************************************** 1706 * 1707 * @macro: 1708 * FT_HAS_SBIX 1709 * 1710 * @description: 1711 * A macro that returns true whenever a face object contains an 'sbix' 1712 * OpenType table *and* outline glyphs. 1713 * 1714 * Currently, FreeType only supports bitmap glyphs in PNG format for this 1715 * table (i.e., JPEG and TIFF formats are unsupported, as are 1716 * Apple-specific formats not part of the OpenType specification). 1717 * 1718 * @note: 1719 * For backward compatibility, a font with an 'sbix' table is treated as 1720 * a bitmap-only face. Using @FT_Open_Face with 1721 * @FT_PARAM_TAG_IGNORE_SBIX, an application can switch off 'sbix' 1722 * handling so that the face is treated as an ordinary outline font with 1723 * scalable outlines. 1724 * 1725 * Here is some pseudo code that roughly illustrates how to implement 1726 * 'sbix' handling according to the OpenType specification. 1727 * 1728 * ``` 1729 * if ( FT_HAS_SBIX( face ) ) 1730 * { 1731 * // open font as a scalable one without sbix handling 1732 * FT_Face face2; 1733 * FT_Parameter param = { FT_PARAM_TAG_IGNORE_SBIX, NULL }; 1734 * FT_Open_Args args = { FT_OPEN_PARAMS | ..., 1735 * ..., 1736 * 1, ¶m }; 1737 * 1738 * 1739 * FT_Open_Face( library, &args, 0, &face2 ); 1740 * 1741 * <sort `face->available_size` as necessary into 1742 * `preferred_sizes`[*]> 1743 * 1744 * for ( i = 0; i < face->num_fixed_sizes; i++ ) 1745 * { 1746 * size = preferred_sizes[i].size; 1747 * 1748 * error = FT_Set_Pixel_Sizes( face, size, size ); 1749 * <error handling omitted> 1750 * 1751 * // check whether we have a glyph in a bitmap strike 1752 * error = FT_Load_Glyph( face, 1753 * glyph_index, 1754 * FT_LOAD_SBITS_ONLY | 1755 * FT_LOAD_BITMAP_METRICS_ONLY ); 1756 * if ( error == FT_Err_Invalid_Argument ) 1757 * continue; 1758 * else if ( error ) 1759 * <other error handling omitted> 1760 * else 1761 * break; 1762 * } 1763 * 1764 * if ( i != face->num_fixed_sizes ) 1765 * <load embedded bitmap with `FT_Load_Glyph`, 1766 * scale it, display it, etc.> 1767 * 1768 * if ( i == face->num_fixed_sizes || 1769 * FT_HAS_SBIX_OVERLAY( face ) ) 1770 * <use `face2` to load outline glyph with `FT_Load_Glyph`, 1771 * scale it, display it on top of the bitmap, etc.> 1772 * } 1773 * ``` 1774 * 1775 * [*] Assuming a target value of 400dpi and available strike sizes 100, 1776 * 200, 300, and 400dpi, a possible order might be [400, 200, 300, 100]: 1777 * scaling 200dpi to 400dpi usually gives better results than scaling 1778 * 300dpi to 400dpi; it is also much faster. However, scaling 100dpi to 1779 * 400dpi can yield a too pixelated result, thus the preference might be 1780 * 300dpi over 100dpi. 1781 * 1782 * @since: 1783 * 2.12 1784 */ 1785 #define FT_HAS_SBIX( face ) \ 1786 ( !!( (face)->face_flags & FT_FACE_FLAG_SBIX ) ) 1787 1788 1789 /************************************************************************** 1790 * 1791 * @macro: 1792 * FT_HAS_SBIX_OVERLAY 1793 * 1794 * @description: 1795 * A macro that returns true whenever a face object contains an 'sbix' 1796 * OpenType table with bit~1 in its `flags` field set, instructing the 1797 * application to overlay the bitmap strike with the corresponding 1798 * outline glyph. See @FT_HAS_SBIX for pseudo code how to use it. 1799 * 1800 * @since: 1801 * 2.12 1802 */ 1803 #define FT_HAS_SBIX_OVERLAY( face ) \ 1804 ( !!( (face)->face_flags & FT_FACE_FLAG_SBIX_OVERLAY ) ) 1805 1806 1807 /************************************************************************** 1808 * 1809 * @section: 1810 * face_creation 1811 * 1812 */ 1813 1814 /************************************************************************** 1815 * 1816 * @enum: 1817 * FT_STYLE_FLAG_XXX 1818 * 1819 * @description: 1820 * A list of bit flags to indicate the style of a given face. These are 1821 * used in the `style_flags` field of @FT_FaceRec. 1822 * 1823 * @values: 1824 * FT_STYLE_FLAG_ITALIC :: 1825 * The face style is italic or oblique. 1826 * 1827 * FT_STYLE_FLAG_BOLD :: 1828 * The face is bold. 1829 * 1830 * @note: 1831 * The style information as provided by FreeType is very basic. More 1832 * details are beyond the scope and should be done on a higher level (for 1833 * example, by analyzing various fields of the 'OS/2' table in SFNT based 1834 * fonts). 1835 */ 1836 #define FT_STYLE_FLAG_ITALIC ( 1 << 0 ) 1837 #define FT_STYLE_FLAG_BOLD ( 1 << 1 ) 1838 1839 1840 /************************************************************************** 1841 * 1842 * @section: 1843 * other_api_data 1844 * 1845 */ 1846 1847 /************************************************************************** 1848 * 1849 * @type: 1850 * FT_Size_Internal 1851 * 1852 * @description: 1853 * An opaque handle to an `FT_Size_InternalRec` structure, used to model 1854 * private data of a given @FT_Size object. 1855 */ 1856 typedef struct FT_Size_InternalRec_* FT_Size_Internal; 1857 1858 1859 /************************************************************************** 1860 * 1861 * @section: 1862 * sizing_and_scaling 1863 * 1864 */ 1865 1866 /************************************************************************** 1867 * 1868 * @struct: 1869 * FT_Size_Metrics 1870 * 1871 * @description: 1872 * The size metrics structure gives the metrics of a size object. 1873 * 1874 * @fields: 1875 * x_ppem :: 1876 * The width of the scaled EM square in pixels, hence the term 'ppem' 1877 * (pixels per EM). It is also referred to as 'nominal width'. 1878 * 1879 * y_ppem :: 1880 * The height of the scaled EM square in pixels, hence the term 'ppem' 1881 * (pixels per EM). It is also referred to as 'nominal height'. 1882 * 1883 * x_scale :: 1884 * A 16.16 fractional scaling value to convert horizontal metrics from 1885 * font units to 26.6 fractional pixels. Only relevant for scalable 1886 * font formats. 1887 * 1888 * y_scale :: 1889 * A 16.16 fractional scaling value to convert vertical metrics from 1890 * font units to 26.6 fractional pixels. Only relevant for scalable 1891 * font formats. 1892 * 1893 * ascender :: 1894 * The ascender in 26.6 fractional pixels, rounded up to an integer 1895 * value. See @FT_FaceRec for the details. 1896 * 1897 * descender :: 1898 * The descender in 26.6 fractional pixels, rounded down to an integer 1899 * value. See @FT_FaceRec for the details. 1900 * 1901 * height :: 1902 * The height in 26.6 fractional pixels, rounded to an integer value. 1903 * See @FT_FaceRec for the details. 1904 * 1905 * max_advance :: 1906 * The maximum advance width in 26.6 fractional pixels, rounded to an 1907 * integer value. See @FT_FaceRec for the details. 1908 * 1909 * @note: 1910 * The scaling values, if relevant, are determined first during a size 1911 * changing operation. The remaining fields are then set by the driver. 1912 * For scalable formats, they are usually set to scaled values of the 1913 * corresponding fields in @FT_FaceRec. Some values like ascender or 1914 * descender are rounded for historical reasons; more precise values (for 1915 * outline fonts) can be derived by scaling the corresponding @FT_FaceRec 1916 * values manually, with code similar to the following. 1917 * 1918 * ``` 1919 * scaled_ascender = FT_MulFix( face->ascender, 1920 * size_metrics->y_scale ); 1921 * ``` 1922 * 1923 * Note that due to glyph hinting and the selected rendering mode these 1924 * values are usually not exact; consequently, they must be treated as 1925 * unreliable with an error margin of at least one pixel! 1926 * 1927 * Indeed, the only way to get the exact metrics is to render _all_ 1928 * glyphs. As this would be a definite performance hit, it is up to 1929 * client applications to perform such computations. 1930 * 1931 * The `FT_Size_Metrics` structure is valid for bitmap fonts also. 1932 * 1933 * 1934 * **TrueType fonts with native bytecode hinting** 1935 * 1936 * All applications that handle TrueType fonts with native hinting must 1937 * be aware that TTFs expect different rounding of vertical font 1938 * dimensions. The application has to cater for this, especially if it 1939 * wants to rely on a TTF's vertical data (for example, to properly align 1940 * box characters vertically). 1941 * 1942 * Only the application knows _in advance_ that it is going to use native 1943 * hinting for TTFs! FreeType, on the other hand, selects the hinting 1944 * mode not at the time of creating an @FT_Size object but much later, 1945 * namely while calling @FT_Load_Glyph. 1946 * 1947 * Here is some pseudo code that illustrates a possible solution. 1948 * 1949 * ``` 1950 * font_format = FT_Get_Font_Format( face ); 1951 * 1952 * if ( !strcmp( font_format, "TrueType" ) && 1953 * do_native_bytecode_hinting ) 1954 * { 1955 * ascender = ROUND( FT_MulFix( face->ascender, 1956 * size_metrics->y_scale ) ); 1957 * descender = ROUND( FT_MulFix( face->descender, 1958 * size_metrics->y_scale ) ); 1959 * } 1960 * else 1961 * { 1962 * ascender = size_metrics->ascender; 1963 * descender = size_metrics->descender; 1964 * } 1965 * 1966 * height = size_metrics->height; 1967 * max_advance = size_metrics->max_advance; 1968 * ``` 1969 */ 1970 typedef struct FT_Size_Metrics_ 1971 { 1972 FT_UShort x_ppem; /* horizontal pixels per EM */ 1973 FT_UShort y_ppem; /* vertical pixels per EM */ 1974 1975 FT_Fixed x_scale; /* scaling values used to convert font */ 1976 FT_Fixed y_scale; /* units to 26.6 fractional pixels */ 1977 1978 FT_Pos ascender; /* ascender in 26.6 frac. pixels */ 1979 FT_Pos descender; /* descender in 26.6 frac. pixels */ 1980 FT_Pos height; /* text height in 26.6 frac. pixels */ 1981 FT_Pos max_advance; /* max horizontal advance, in 26.6 pixels */ 1982 1983 } FT_Size_Metrics; 1984 1985 1986 /************************************************************************** 1987 * 1988 * @struct: 1989 * FT_SizeRec 1990 * 1991 * @description: 1992 * FreeType root size class structure. A size object models a face 1993 * object at a given size. 1994 * 1995 * @fields: 1996 * face :: 1997 * Handle to the parent face object. 1998 * 1999 * generic :: 2000 * A typeless pointer, unused by the FreeType library or any of its 2001 * drivers. It can be used by client applications to link their own 2002 * data to each size object. 2003 * 2004 * metrics :: 2005 * Metrics for this size object. This field is read-only. 2006 */ 2007 typedef struct FT_SizeRec_ 2008 { 2009 FT_Face face; /* parent face object */ 2010 FT_Generic generic; /* generic pointer for client uses */ 2011 FT_Size_Metrics metrics; /* size metrics */ 2012 FT_Size_Internal internal; 2013 2014 } FT_SizeRec; 2015 2016 2017 /************************************************************************** 2018 * 2019 * @section: 2020 * other_api_data 2021 * 2022 */ 2023 2024 /************************************************************************** 2025 * 2026 * @struct: 2027 * FT_SubGlyph 2028 * 2029 * @description: 2030 * The subglyph structure is an internal object used to describe 2031 * subglyphs (for example, in the case of composites). 2032 * 2033 * @note: 2034 * The subglyph implementation is not part of the high-level API, hence 2035 * the forward structure declaration. 2036 * 2037 * You can however retrieve subglyph information with 2038 * @FT_Get_SubGlyph_Info. 2039 */ 2040 typedef struct FT_SubGlyphRec_* FT_SubGlyph; 2041 2042 2043 /************************************************************************** 2044 * 2045 * @type: 2046 * FT_Slot_Internal 2047 * 2048 * @description: 2049 * An opaque handle to an `FT_Slot_InternalRec` structure, used to model 2050 * private data of a given @FT_GlyphSlot object. 2051 */ 2052 typedef struct FT_Slot_InternalRec_* FT_Slot_Internal; 2053 2054 2055 /************************************************************************** 2056 * 2057 * @section: 2058 * glyph_retrieval 2059 * 2060 */ 2061 2062 /************************************************************************** 2063 * 2064 * @struct: 2065 * FT_GlyphSlotRec 2066 * 2067 * @description: 2068 * FreeType root glyph slot class structure. A glyph slot is a container 2069 * where individual glyphs can be loaded, be they in outline or bitmap 2070 * format. 2071 * 2072 * @fields: 2073 * library :: 2074 * A handle to the FreeType library instance this slot belongs to. 2075 * 2076 * face :: 2077 * A handle to the parent face object. 2078 * 2079 * next :: 2080 * In some cases (like some font tools), several glyph slots per face 2081 * object can be a good thing. As this is rare, the glyph slots are 2082 * listed through a direct, single-linked list using its `next` field. 2083 * 2084 * glyph_index :: 2085 * [Since 2.10] The glyph index passed as an argument to @FT_Load_Glyph 2086 * while initializing the glyph slot. 2087 * 2088 * generic :: 2089 * A typeless pointer unused by the FreeType library or any of its 2090 * drivers. It can be used by client applications to link their own 2091 * data to each glyph slot object. 2092 * 2093 * metrics :: 2094 * The metrics of the last loaded glyph in the slot. The returned 2095 * values depend on the last load flags (see the @FT_Load_Glyph API 2096 * function) and can be expressed either in 26.6 fractional pixels or 2097 * font units. 2098 * 2099 * Note that even when the glyph image is transformed, the metrics are 2100 * not. 2101 * 2102 * linearHoriAdvance :: 2103 * The advance width of the unhinted glyph. Its value is expressed in 2104 * 16.16 fractional pixels, unless @FT_LOAD_LINEAR_DESIGN is set when 2105 * loading the glyph. This field can be important to perform correct 2106 * WYSIWYG layout. Only relevant for scalable glyphs. 2107 * 2108 * linearVertAdvance :: 2109 * The advance height of the unhinted glyph. Its value is expressed in 2110 * 16.16 fractional pixels, unless @FT_LOAD_LINEAR_DESIGN is set when 2111 * loading the glyph. This field can be important to perform correct 2112 * WYSIWYG layout. Only relevant for scalable glyphs. 2113 * 2114 * advance :: 2115 * This shorthand is, depending on @FT_LOAD_IGNORE_TRANSFORM, the 2116 * transformed (hinted) advance width for the glyph, in 26.6 fractional 2117 * pixel format. As specified with @FT_LOAD_VERTICAL_LAYOUT, it uses 2118 * either the `horiAdvance` or the `vertAdvance` value of `metrics` 2119 * field. 2120 * 2121 * format :: 2122 * This field indicates the format of the image contained in the glyph 2123 * slot. Typically @FT_GLYPH_FORMAT_BITMAP, @FT_GLYPH_FORMAT_OUTLINE, 2124 * or @FT_GLYPH_FORMAT_COMPOSITE, but other values are possible. 2125 * 2126 * bitmap :: 2127 * This field is used as a bitmap descriptor. Note that the address 2128 * and content of the bitmap buffer can change between calls of 2129 * @FT_Load_Glyph and a few other functions. 2130 * 2131 * bitmap_left :: 2132 * The bitmap's left bearing expressed in integer pixels. 2133 * 2134 * bitmap_top :: 2135 * The bitmap's top bearing expressed in integer pixels. This is the 2136 * distance from the baseline to the top-most glyph scanline, upwards 2137 * y~coordinates being **positive**. 2138 * 2139 * outline :: 2140 * The outline descriptor for the current glyph image if its format is 2141 * @FT_GLYPH_FORMAT_OUTLINE. Once a glyph is loaded, `outline` can be 2142 * transformed, distorted, emboldened, etc. However, it must not be 2143 * freed. 2144 * 2145 * [Since 2.10.1] If @FT_LOAD_NO_SCALE is set, outline coordinates of 2146 * OpenType variation fonts for a selected instance are internally 2147 * handled as 26.6 fractional font units but returned as (rounded) 2148 * integers, as expected. To get unrounded font units, don't use 2149 * @FT_LOAD_NO_SCALE but load the glyph with @FT_LOAD_NO_HINTING and 2150 * scale it, using the font's `units_per_EM` value as the ppem. 2151 * 2152 * num_subglyphs :: 2153 * The number of subglyphs in a composite glyph. This field is only 2154 * valid for the composite glyph format that should normally only be 2155 * loaded with the @FT_LOAD_NO_RECURSE flag. 2156 * 2157 * subglyphs :: 2158 * An array of subglyph descriptors for composite glyphs. There are 2159 * `num_subglyphs` elements in there. Currently internal to FreeType. 2160 * 2161 * control_data :: 2162 * Certain font drivers can also return the control data for a given 2163 * glyph image (e.g. TrueType bytecode, Type~1 charstrings, etc.). 2164 * This field is a pointer to such data; it is currently internal to 2165 * FreeType. 2166 * 2167 * control_len :: 2168 * This is the length in bytes of the control data. Currently internal 2169 * to FreeType. 2170 * 2171 * other :: 2172 * Reserved. 2173 * 2174 * lsb_delta :: 2175 * The difference between hinted and unhinted left side bearing while 2176 * auto-hinting is active. Zero otherwise. 2177 * 2178 * rsb_delta :: 2179 * The difference between hinted and unhinted right side bearing while 2180 * auto-hinting is active. Zero otherwise. 2181 * 2182 * @note: 2183 * If @FT_Load_Glyph is called with default flags (see @FT_LOAD_DEFAULT) 2184 * the glyph image is loaded in the glyph slot in its native format 2185 * (e.g., an outline glyph for TrueType and Type~1 formats). [Since 2.9] 2186 * The prospective bitmap metrics are calculated according to 2187 * @FT_LOAD_TARGET_XXX and other flags even for the outline glyph, even 2188 * if @FT_LOAD_RENDER is not set. 2189 * 2190 * This image can later be converted into a bitmap by calling 2191 * @FT_Render_Glyph. This function searches the current renderer for the 2192 * native image's format, then invokes it. 2193 * 2194 * The renderer is in charge of transforming the native image through the 2195 * slot's face transformation fields, then converting it into a bitmap 2196 * that is returned in `slot->bitmap`. 2197 * 2198 * Note that `slot->bitmap_left` and `slot->bitmap_top` are also used to 2199 * specify the position of the bitmap relative to the current pen 2200 * position (e.g., coordinates (0,0) on the baseline). Of course, 2201 * `slot->format` is also changed to @FT_GLYPH_FORMAT_BITMAP. 2202 * 2203 * Here is a small pseudo code fragment that shows how to use `lsb_delta` 2204 * and `rsb_delta` to do fractional positioning of glyphs: 2205 * 2206 * ``` 2207 * FT_GlyphSlot slot = face->glyph; 2208 * FT_Pos origin_x = 0; 2209 * 2210 * 2211 * for all glyphs do 2212 * <load glyph with `FT_Load_Glyph'> 2213 * 2214 * FT_Outline_Translate( slot->outline, origin_x & 63, 0 ); 2215 * 2216 * <save glyph image, or render glyph, or ...> 2217 * 2218 * <compute kern between current and next glyph 2219 * and add it to `origin_x'> 2220 * 2221 * origin_x += slot->advance.x; 2222 * origin_x += slot->lsb_delta - slot->rsb_delta; 2223 * endfor 2224 * ``` 2225 * 2226 * Here is another small pseudo code fragment that shows how to use 2227 * `lsb_delta` and `rsb_delta` to improve integer positioning of glyphs: 2228 * 2229 * ``` 2230 * FT_GlyphSlot slot = face->glyph; 2231 * FT_Pos origin_x = 0; 2232 * FT_Pos prev_rsb_delta = 0; 2233 * 2234 * 2235 * for all glyphs do 2236 * <compute kern between current and previous glyph 2237 * and add it to `origin_x'> 2238 * 2239 * <load glyph with `FT_Load_Glyph'> 2240 * 2241 * if ( prev_rsb_delta - slot->lsb_delta > 32 ) 2242 * origin_x -= 64; 2243 * else if ( prev_rsb_delta - slot->lsb_delta < -31 ) 2244 * origin_x += 64; 2245 * 2246 * prev_rsb_delta = slot->rsb_delta; 2247 * 2248 * <save glyph image, or render glyph, or ...> 2249 * 2250 * origin_x += slot->advance.x; 2251 * endfor 2252 * ``` 2253 * 2254 * If you use strong auto-hinting, you **must** apply these delta values! 2255 * Otherwise you will experience far too large inter-glyph spacing at 2256 * small rendering sizes in most cases. Note that it doesn't harm to use 2257 * the above code for other hinting modes also, since the delta values 2258 * are zero then. 2259 */ 2260 typedef struct FT_GlyphSlotRec_ 2261 { 2262 FT_Library library; 2263 FT_Face face; 2264 FT_GlyphSlot next; 2265 FT_UInt glyph_index; /* new in 2.10; was reserved previously */ 2266 FT_Generic generic; 2267 2268 FT_Glyph_Metrics metrics; 2269 FT_Fixed linearHoriAdvance; 2270 FT_Fixed linearVertAdvance; 2271 FT_Vector advance; 2272 2273 FT_Glyph_Format format; 2274 2275 FT_Bitmap bitmap; 2276 FT_Int bitmap_left; 2277 FT_Int bitmap_top; 2278 2279 FT_Outline outline; 2280 2281 FT_UInt num_subglyphs; 2282 FT_SubGlyph subglyphs; 2283 2284 void* control_data; 2285 long control_len; 2286 2287 FT_Pos lsb_delta; 2288 FT_Pos rsb_delta; 2289 2290 void* other; 2291 2292 FT_Slot_Internal internal; 2293 2294 } FT_GlyphSlotRec; 2295 2296 2297 /*************************************************************************/ 2298 /*************************************************************************/ 2299 /* */ 2300 /* F U N C T I O N S */ 2301 /* */ 2302 /*************************************************************************/ 2303 /*************************************************************************/ 2304 2305 2306 /************************************************************************** 2307 * 2308 * @section: 2309 * library_setup 2310 * 2311 */ 2312 2313 /************************************************************************** 2314 * 2315 * @function: 2316 * FT_Init_FreeType 2317 * 2318 * @description: 2319 * Initialize a new FreeType library object. The set of modules that are 2320 * registered by this function is determined at build time. 2321 * 2322 * @output: 2323 * alibrary :: 2324 * A handle to a new library object. 2325 * 2326 * @return: 2327 * FreeType error code. 0~means success. 2328 * 2329 * @note: 2330 * In case you want to provide your own memory allocating routines, use 2331 * @FT_New_Library instead, followed by a call to @FT_Add_Default_Modules 2332 * (or a series of calls to @FT_Add_Module) and 2333 * @FT_Set_Default_Properties. 2334 * 2335 * See the documentation of @FT_Library and @FT_Face for multi-threading 2336 * issues. 2337 * 2338 * If you need reference-counting (cf. @FT_Reference_Library), use 2339 * @FT_New_Library and @FT_Done_Library. 2340 * 2341 * If compilation option `FT_CONFIG_OPTION_ENVIRONMENT_PROPERTIES` is 2342 * set, this function reads the `FREETYPE_PROPERTIES` environment 2343 * variable to control driver properties. See section @properties for 2344 * more. 2345 */ 2346 FT_EXPORT( FT_Error ) 2347 FT_Init_FreeType( FT_Library *alibrary ); 2348 2349 2350 /************************************************************************** 2351 * 2352 * @function: 2353 * FT_Done_FreeType 2354 * 2355 * @description: 2356 * Destroy a given FreeType library object and all of its children, 2357 * including resources, drivers, faces, sizes, etc. 2358 * 2359 * @input: 2360 * library :: 2361 * A handle to the target library object. 2362 * 2363 * @return: 2364 * FreeType error code. 0~means success. 2365 */ 2366 FT_EXPORT( FT_Error ) 2367 FT_Done_FreeType( FT_Library library ); 2368 2369 2370 /************************************************************************** 2371 * 2372 * @section: 2373 * face_creation 2374 * 2375 */ 2376 2377 /************************************************************************** 2378 * 2379 * @enum: 2380 * FT_OPEN_XXX 2381 * 2382 * @description: 2383 * A list of bit field constants used within the `flags` field of the 2384 * @FT_Open_Args structure. 2385 * 2386 * @values: 2387 * FT_OPEN_MEMORY :: 2388 * This is a memory-based stream. 2389 * 2390 * FT_OPEN_STREAM :: 2391 * Copy the stream from the `stream` field. 2392 * 2393 * FT_OPEN_PATHNAME :: 2394 * Create a new input stream from a C~path name. 2395 * 2396 * FT_OPEN_DRIVER :: 2397 * Use the `driver` field. 2398 * 2399 * FT_OPEN_PARAMS :: 2400 * Use the `num_params` and `params` fields. 2401 * 2402 * @note: 2403 * The `FT_OPEN_MEMORY`, `FT_OPEN_STREAM`, and `FT_OPEN_PATHNAME` flags 2404 * are mutually exclusive. 2405 */ 2406 #define FT_OPEN_MEMORY 0x1 2407 #define FT_OPEN_STREAM 0x2 2408 #define FT_OPEN_PATHNAME 0x4 2409 #define FT_OPEN_DRIVER 0x8 2410 #define FT_OPEN_PARAMS 0x10 2411 2412 2413 /* these constants are deprecated; use the corresponding `FT_OPEN_XXX` */ 2414 /* values instead */ 2415 #define ft_open_memory FT_OPEN_MEMORY 2416 #define ft_open_stream FT_OPEN_STREAM 2417 #define ft_open_pathname FT_OPEN_PATHNAME 2418 #define ft_open_driver FT_OPEN_DRIVER 2419 #define ft_open_params FT_OPEN_PARAMS 2420 2421 2422 /************************************************************************** 2423 * 2424 * @struct: 2425 * FT_Parameter 2426 * 2427 * @description: 2428 * A simple structure to pass more or less generic parameters to 2429 * @FT_Open_Face and @FT_Face_Properties. 2430 * 2431 * @fields: 2432 * tag :: 2433 * A four-byte identification tag. 2434 * 2435 * data :: 2436 * A pointer to the parameter data. 2437 * 2438 * @note: 2439 * The ID and function of parameters are driver-specific. See section 2440 * @parameter_tags for more information. 2441 */ 2442 typedef struct FT_Parameter_ 2443 { 2444 FT_ULong tag; 2445 FT_Pointer data; 2446 2447 } FT_Parameter; 2448 2449 2450 /************************************************************************** 2451 * 2452 * @struct: 2453 * FT_Open_Args 2454 * 2455 * @description: 2456 * A structure to indicate how to open a new font file or stream. A 2457 * pointer to such a structure can be used as a parameter for the 2458 * functions @FT_Open_Face and @FT_Attach_Stream. 2459 * 2460 * @fields: 2461 * flags :: 2462 * A set of bit flags indicating how to use the structure. 2463 * 2464 * memory_base :: 2465 * The first byte of the file in memory. 2466 * 2467 * memory_size :: 2468 * The size in bytes of the file in memory. 2469 * 2470 * pathname :: 2471 * A pointer to an 8-bit file pathname, which must be a C~string (i.e., 2472 * no null bytes except at the very end). The pointer is not owned by 2473 * FreeType. 2474 * 2475 * stream :: 2476 * A handle to a source stream object. 2477 * 2478 * driver :: 2479 * This field is exclusively used by @FT_Open_Face; it simply specifies 2480 * the font driver to use for opening the face. If set to `NULL`, 2481 * FreeType tries to load the face with each one of the drivers in its 2482 * list. 2483 * 2484 * num_params :: 2485 * The number of extra parameters. 2486 * 2487 * params :: 2488 * Extra parameters passed to the font driver when opening a new face. 2489 * 2490 * @note: 2491 * The stream type is determined by the contents of `flags`: 2492 * 2493 * If the @FT_OPEN_MEMORY bit is set, assume that this is a memory file 2494 * of `memory_size` bytes, located at `memory_address`. The data are not 2495 * copied, and the client is responsible for releasing and destroying 2496 * them _after_ the corresponding call to @FT_Done_Face. 2497 * 2498 * Otherwise, if the @FT_OPEN_STREAM bit is set, assume that a custom 2499 * input stream `stream` is used. 2500 * 2501 * Otherwise, if the @FT_OPEN_PATHNAME bit is set, assume that this is a 2502 * normal file and use `pathname` to open it. 2503 * 2504 * If none of the above bits are set or if multiple are set at the same 2505 * time, the flags are invalid and @FT_Open_Face fails. 2506 * 2507 * If the @FT_OPEN_DRIVER bit is set, @FT_Open_Face only tries to open 2508 * the file with the driver whose handler is in `driver`. 2509 * 2510 * If the @FT_OPEN_PARAMS bit is set, the parameters given by 2511 * `num_params` and `params` is used. They are ignored otherwise. 2512 * 2513 * Ideally, both the `pathname` and `params` fields should be tagged as 2514 * 'const'; this is missing for API backward compatibility. In other 2515 * words, applications should treat them as read-only. 2516 */ 2517 typedef struct FT_Open_Args_ 2518 { 2519 FT_UInt flags; 2520 const FT_Byte* memory_base; 2521 FT_Long memory_size; 2522 FT_String* pathname; 2523 FT_Stream stream; 2524 FT_Module driver; 2525 FT_Int num_params; 2526 FT_Parameter* params; 2527 2528 } FT_Open_Args; 2529 2530 2531 /************************************************************************** 2532 * 2533 * @function: 2534 * FT_New_Face 2535 * 2536 * @description: 2537 * Call @FT_Open_Face to open a font by its pathname. 2538 * 2539 * @inout: 2540 * library :: 2541 * A handle to the library resource. 2542 * 2543 * @input: 2544 * pathname :: 2545 * A path to the font file. 2546 * 2547 * face_index :: 2548 * See @FT_Open_Face for a detailed description of this parameter. 2549 * 2550 * @output: 2551 * aface :: 2552 * A handle to a new face object. If `face_index` is greater than or 2553 * equal to zero, it must be non-`NULL`. 2554 * 2555 * @return: 2556 * FreeType error code. 0~means success. 2557 * 2558 * @note: 2559 * The `pathname` string should be recognizable as such by a standard 2560 * `fopen` call on your system; in particular, this means that `pathname` 2561 * must not contain null bytes. If that is not sufficient to address all 2562 * file name possibilities (for example, to handle wide character file 2563 * names on Windows in UTF-16 encoding) you might use @FT_Open_Face to 2564 * pass a memory array or a stream object instead. 2565 * 2566 * Use @FT_Done_Face to destroy the created @FT_Face object (along with 2567 * its slot and sizes). 2568 */ 2569 FT_EXPORT( FT_Error ) 2570 FT_New_Face( FT_Library library, 2571 const char* filepathname, 2572 FT_Long face_index, 2573 FT_Face *aface ); 2574 2575 2576 /************************************************************************** 2577 * 2578 * @function: 2579 * FT_New_Memory_Face 2580 * 2581 * @description: 2582 * Call @FT_Open_Face to open a font that has been loaded into memory. 2583 * 2584 * @inout: 2585 * library :: 2586 * A handle to the library resource. 2587 * 2588 * @input: 2589 * file_base :: 2590 * A pointer to the beginning of the font data. 2591 * 2592 * file_size :: 2593 * The size of the memory chunk used by the font data. 2594 * 2595 * face_index :: 2596 * See @FT_Open_Face for a detailed description of this parameter. 2597 * 2598 * @output: 2599 * aface :: 2600 * A handle to a new face object. If `face_index` is greater than or 2601 * equal to zero, it must be non-`NULL`. 2602 * 2603 * @return: 2604 * FreeType error code. 0~means success. 2605 * 2606 * @note: 2607 * You must not deallocate the memory before calling @FT_Done_Face. 2608 */ 2609 FT_EXPORT( FT_Error ) 2610 FT_New_Memory_Face( FT_Library library, 2611 const FT_Byte* file_base, 2612 FT_Long file_size, 2613 FT_Long face_index, 2614 FT_Face *aface ); 2615 2616 2617 /************************************************************************** 2618 * 2619 * @function: 2620 * FT_Open_Face 2621 * 2622 * @description: 2623 * Create a face object from a given resource described by @FT_Open_Args. 2624 * 2625 * @inout: 2626 * library :: 2627 * A handle to the library resource. 2628 * 2629 * @input: 2630 * args :: 2631 * A pointer to an `FT_Open_Args` structure that must be filled by the 2632 * caller. 2633 * 2634 * face_index :: 2635 * This field holds two different values. Bits 0-15 are the index of 2636 * the face in the font file (starting with value~0). Set it to~0 if 2637 * there is only one face in the font file. 2638 * 2639 * [Since 2.6.1] Bits 16-30 are relevant to GX and OpenType variation 2640 * fonts only, specifying the named instance index for the current face 2641 * index (starting with value~1; value~0 makes FreeType ignore named 2642 * instances). For non-variation fonts, bits 16-30 are ignored. 2643 * Assuming that you want to access the third named instance in face~4, 2644 * `face_index` should be set to 0x00030004. If you want to access 2645 * face~4 without variation handling, simply set `face_index` to 2646 * value~4. 2647 * 2648 * `FT_Open_Face` and its siblings can be used to quickly check whether 2649 * the font format of a given font resource is supported by FreeType. 2650 * In general, if the `face_index` argument is negative, the function's 2651 * return value is~0 if the font format is recognized, or non-zero 2652 * otherwise. The function allocates a more or less empty face handle 2653 * in `*aface` (if `aface` isn't `NULL`); the only two useful fields in 2654 * this special case are `face->num_faces` and `face->style_flags`. 2655 * For any negative value of `face_index`, `face->num_faces` gives the 2656 * number of faces within the font file. For the negative value 2657 * '-(N+1)' (with 'N' a non-negative 16-bit value), bits 16-30 in 2658 * `face->style_flags` give the number of named instances in face 'N' 2659 * if we have a variation font (or zero otherwise). After examination, 2660 * the returned @FT_Face structure should be deallocated with a call to 2661 * @FT_Done_Face. 2662 * 2663 * @output: 2664 * aface :: 2665 * A handle to a new face object. If `face_index` is greater than or 2666 * equal to zero, it must be non-`NULL`. 2667 * 2668 * @return: 2669 * FreeType error code. 0~means success. 2670 * 2671 * @note: 2672 * Unlike FreeType 1.x, this function automatically creates a glyph slot 2673 * for the face object that can be accessed directly through 2674 * `face->glyph`. 2675 * 2676 * Each new face object created with this function also owns a default 2677 * @FT_Size object, accessible as `face->size`. 2678 * 2679 * One @FT_Library instance can have multiple face objects, that is, 2680 * @FT_Open_Face and its siblings can be called multiple times using the 2681 * same `library` argument. 2682 * 2683 * See the discussion of reference counters in the description of 2684 * @FT_Reference_Face. 2685 * 2686 * If `FT_OPEN_STREAM` is set in `args->flags`, the stream in 2687 * `args->stream` is automatically closed before this function returns 2688 * any error (including `FT_Err_Invalid_Argument`). 2689 * 2690 * @example: 2691 * To loop over all faces, use code similar to the following snippet 2692 * (omitting the error handling). 2693 * 2694 * ``` 2695 * ... 2696 * FT_Face face; 2697 * FT_Long i, num_faces; 2698 * 2699 * 2700 * error = FT_Open_Face( library, args, -1, &face ); 2701 * if ( error ) { ... } 2702 * 2703 * num_faces = face->num_faces; 2704 * FT_Done_Face( face ); 2705 * 2706 * for ( i = 0; i < num_faces; i++ ) 2707 * { 2708 * ... 2709 * error = FT_Open_Face( library, args, i, &face ); 2710 * ... 2711 * FT_Done_Face( face ); 2712 * ... 2713 * } 2714 * ``` 2715 * 2716 * To loop over all valid values for `face_index`, use something similar 2717 * to the following snippet, again without error handling. The code 2718 * accesses all faces immediately (thus only a single call of 2719 * `FT_Open_Face` within the do-loop), with and without named instances. 2720 * 2721 * ``` 2722 * ... 2723 * FT_Face face; 2724 * 2725 * FT_Long num_faces = 0; 2726 * FT_Long num_instances = 0; 2727 * 2728 * FT_Long face_idx = 0; 2729 * FT_Long instance_idx = 0; 2730 * 2731 * 2732 * do 2733 * { 2734 * FT_Long id = ( instance_idx << 16 ) + face_idx; 2735 * 2736 * 2737 * error = FT_Open_Face( library, args, id, &face ); 2738 * if ( error ) { ... } 2739 * 2740 * num_faces = face->num_faces; 2741 * num_instances = face->style_flags >> 16; 2742 * 2743 * ... 2744 * 2745 * FT_Done_Face( face ); 2746 * 2747 * if ( instance_idx < num_instances ) 2748 * instance_idx++; 2749 * else 2750 * { 2751 * face_idx++; 2752 * instance_idx = 0; 2753 * } 2754 * 2755 * } while ( face_idx < num_faces ) 2756 * ``` 2757 */ 2758 FT_EXPORT( FT_Error ) 2759 FT_Open_Face( FT_Library library, 2760 const FT_Open_Args* args, 2761 FT_Long face_index, 2762 FT_Face *aface ); 2763 2764 2765 /************************************************************************** 2766 * 2767 * @function: 2768 * FT_Attach_File 2769 * 2770 * @description: 2771 * Call @FT_Attach_Stream to attach a file. 2772 * 2773 * @inout: 2774 * face :: 2775 * The target face object. 2776 * 2777 * @input: 2778 * filepathname :: 2779 * The pathname. 2780 * 2781 * @return: 2782 * FreeType error code. 0~means success. 2783 */ 2784 FT_EXPORT( FT_Error ) 2785 FT_Attach_File( FT_Face face, 2786 const char* filepathname ); 2787 2788 2789 /************************************************************************** 2790 * 2791 * @function: 2792 * FT_Attach_Stream 2793 * 2794 * @description: 2795 * 'Attach' data to a face object. Normally, this is used to read 2796 * additional information for the face object. For example, you can 2797 * attach an AFM file that comes with a Type~1 font to get the kerning 2798 * values and other metrics. 2799 * 2800 * @inout: 2801 * face :: 2802 * The target face object. 2803 * 2804 * @input: 2805 * parameters :: 2806 * A pointer to @FT_Open_Args that must be filled by the caller. 2807 * 2808 * @return: 2809 * FreeType error code. 0~means success. 2810 * 2811 * @note: 2812 * The meaning of the 'attach' (i.e., what really happens when the new 2813 * file is read) is not fixed by FreeType itself. It really depends on 2814 * the font format (and thus the font driver). 2815 * 2816 * Client applications are expected to know what they are doing when 2817 * invoking this function. Most drivers simply do not implement file or 2818 * stream attachments. 2819 */ 2820 FT_EXPORT( FT_Error ) 2821 FT_Attach_Stream( FT_Face face, 2822 const FT_Open_Args* parameters ); 2823 2824 2825 /************************************************************************** 2826 * 2827 * @function: 2828 * FT_Reference_Face 2829 * 2830 * @description: 2831 * A counter gets initialized to~1 at the time an @FT_Face structure is 2832 * created. This function increments the counter. @FT_Done_Face then 2833 * only destroys a face if the counter is~1, otherwise it simply 2834 * decrements the counter. 2835 * 2836 * This function helps in managing life-cycles of structures that 2837 * reference @FT_Face objects. 2838 * 2839 * @input: 2840 * face :: 2841 * A handle to a target face object. 2842 * 2843 * @return: 2844 * FreeType error code. 0~means success. 2845 * 2846 * @since: 2847 * 2.4.2 2848 * 2849 */ 2850 FT_EXPORT( FT_Error ) 2851 FT_Reference_Face( FT_Face face ); 2852 2853 2854 /************************************************************************** 2855 * 2856 * @function: 2857 * FT_Done_Face 2858 * 2859 * @description: 2860 * Discard a given face object, as well as all of its child slots and 2861 * sizes. 2862 * 2863 * @input: 2864 * face :: 2865 * A handle to a target face object. 2866 * 2867 * @return: 2868 * FreeType error code. 0~means success. 2869 * 2870 * @note: 2871 * See the discussion of reference counters in the description of 2872 * @FT_Reference_Face. 2873 */ 2874 FT_EXPORT( FT_Error ) 2875 FT_Done_Face( FT_Face face ); 2876 2877 2878 /************************************************************************** 2879 * 2880 * @section: 2881 * sizing_and_scaling 2882 * 2883 */ 2884 2885 /************************************************************************** 2886 * 2887 * @function: 2888 * FT_Select_Size 2889 * 2890 * @description: 2891 * Select a bitmap strike. To be more precise, this function sets the 2892 * scaling factors of the active @FT_Size object in a face so that 2893 * bitmaps from this particular strike are taken by @FT_Load_Glyph and 2894 * friends. 2895 * 2896 * @inout: 2897 * face :: 2898 * A handle to a target face object. 2899 * 2900 * @input: 2901 * strike_index :: 2902 * The index of the bitmap strike in the `available_sizes` field of 2903 * @FT_FaceRec structure. 2904 * 2905 * @return: 2906 * FreeType error code. 0~means success. 2907 * 2908 * @note: 2909 * For bitmaps embedded in outline fonts it is common that only a subset 2910 * of the available glyphs at a given ppem value is available. FreeType 2911 * silently uses outlines if there is no bitmap for a given glyph index. 2912 * 2913 * For GX and OpenType variation fonts, a bitmap strike makes sense only 2914 * if the default instance is active (that is, no glyph variation takes 2915 * place); otherwise, FreeType simply ignores bitmap strikes. The same 2916 * is true for all named instances that are different from the default 2917 * instance. 2918 * 2919 * Don't use this function if you are using the FreeType cache API. 2920 */ 2921 FT_EXPORT( FT_Error ) 2922 FT_Select_Size( FT_Face face, 2923 FT_Int strike_index ); 2924 2925 2926 /************************************************************************** 2927 * 2928 * @enum: 2929 * FT_Size_Request_Type 2930 * 2931 * @description: 2932 * An enumeration type that lists the supported size request types, i.e., 2933 * what input size (in font units) maps to the requested output size (in 2934 * pixels, as computed from the arguments of @FT_Size_Request). 2935 * 2936 * @values: 2937 * FT_SIZE_REQUEST_TYPE_NOMINAL :: 2938 * The nominal size. The `units_per_EM` field of @FT_FaceRec is used 2939 * to determine both scaling values. 2940 * 2941 * This is the standard scaling found in most applications. In 2942 * particular, use this size request type for TrueType fonts if they 2943 * provide optical scaling or something similar. Note, however, that 2944 * `units_per_EM` is a rather abstract value which bears no relation to 2945 * the actual size of the glyphs in a font. 2946 * 2947 * FT_SIZE_REQUEST_TYPE_REAL_DIM :: 2948 * The real dimension. The sum of the `ascender` and (minus of) the 2949 * `descender` fields of @FT_FaceRec is used to determine both scaling 2950 * values. 2951 * 2952 * FT_SIZE_REQUEST_TYPE_BBOX :: 2953 * The font bounding box. The width and height of the `bbox` field of 2954 * @FT_FaceRec are used to determine the horizontal and vertical 2955 * scaling value, respectively. 2956 * 2957 * FT_SIZE_REQUEST_TYPE_CELL :: 2958 * The `max_advance_width` field of @FT_FaceRec is used to determine 2959 * the horizontal scaling value; the vertical scaling value is 2960 * determined the same way as @FT_SIZE_REQUEST_TYPE_REAL_DIM does. 2961 * Finally, both scaling values are set to the smaller one. This type 2962 * is useful if you want to specify the font size for, say, a window of 2963 * a given dimension and 80x24 cells. 2964 * 2965 * FT_SIZE_REQUEST_TYPE_SCALES :: 2966 * Specify the scaling values directly. 2967 * 2968 * @note: 2969 * The above descriptions only apply to scalable formats. For bitmap 2970 * formats, the behaviour is up to the driver. 2971 * 2972 * See the note section of @FT_Size_Metrics if you wonder how size 2973 * requesting relates to scaling values. 2974 */ 2975 typedef enum FT_Size_Request_Type_ 2976 { 2977 FT_SIZE_REQUEST_TYPE_NOMINAL, 2978 FT_SIZE_REQUEST_TYPE_REAL_DIM, 2979 FT_SIZE_REQUEST_TYPE_BBOX, 2980 FT_SIZE_REQUEST_TYPE_CELL, 2981 FT_SIZE_REQUEST_TYPE_SCALES, 2982 2983 FT_SIZE_REQUEST_TYPE_MAX 2984 2985 } FT_Size_Request_Type; 2986 2987 2988 /************************************************************************** 2989 * 2990 * @struct: 2991 * FT_Size_RequestRec 2992 * 2993 * @description: 2994 * A structure to model a size request. 2995 * 2996 * @fields: 2997 * type :: 2998 * See @FT_Size_Request_Type. 2999 * 3000 * width :: 3001 * The desired width, given as a 26.6 fractional point value (with 72pt 3002 * = 1in). 3003 * 3004 * height :: 3005 * The desired height, given as a 26.6 fractional point value (with 3006 * 72pt = 1in). 3007 * 3008 * horiResolution :: 3009 * The horizontal resolution (dpi, i.e., pixels per inch). If set to 3010 * zero, `width` is treated as a 26.6 fractional **pixel** value, which 3011 * gets internally rounded to an integer. 3012 * 3013 * vertResolution :: 3014 * The vertical resolution (dpi, i.e., pixels per inch). If set to 3015 * zero, `height` is treated as a 26.6 fractional **pixel** value, 3016 * which gets internally rounded to an integer. 3017 * 3018 * @note: 3019 * If `width` is zero, the horizontal scaling value is set equal to the 3020 * vertical scaling value, and vice versa. 3021 * 3022 * If `type` is `FT_SIZE_REQUEST_TYPE_SCALES`, `width` and `height` are 3023 * interpreted directly as 16.16 fractional scaling values, without any 3024 * further modification, and both `horiResolution` and `vertResolution` 3025 * are ignored. 3026 */ 3027 typedef struct FT_Size_RequestRec_ 3028 { 3029 FT_Size_Request_Type type; 3030 FT_Long width; 3031 FT_Long height; 3032 FT_UInt horiResolution; 3033 FT_UInt vertResolution; 3034 3035 } FT_Size_RequestRec; 3036 3037 3038 /************************************************************************** 3039 * 3040 * @struct: 3041 * FT_Size_Request 3042 * 3043 * @description: 3044 * A handle to a size request structure. 3045 */ 3046 typedef struct FT_Size_RequestRec_ *FT_Size_Request; 3047 3048 3049 /************************************************************************** 3050 * 3051 * @function: 3052 * FT_Request_Size 3053 * 3054 * @description: 3055 * Resize the scale of the active @FT_Size object in a face. 3056 * 3057 * @inout: 3058 * face :: 3059 * A handle to a target face object. 3060 * 3061 * @input: 3062 * req :: 3063 * A pointer to a @FT_Size_RequestRec. 3064 * 3065 * @return: 3066 * FreeType error code. 0~means success. 3067 * 3068 * @note: 3069 * Although drivers may select the bitmap strike matching the request, 3070 * you should not rely on this if you intend to select a particular 3071 * bitmap strike. Use @FT_Select_Size instead in that case. 3072 * 3073 * The relation between the requested size and the resulting glyph size 3074 * is dependent entirely on how the size is defined in the source face. 3075 * The font designer chooses the final size of each glyph relative to 3076 * this size. For more information refer to 3077 * 'https://www.freetype.org/freetype2/docs/glyphs/glyphs-2.html'. 3078 * 3079 * Contrary to @FT_Set_Char_Size, this function doesn't have special code 3080 * to normalize zero-valued widths, heights, or resolutions, which are 3081 * treated as @FT_LOAD_NO_SCALE. 3082 * 3083 * Don't use this function if you are using the FreeType cache API. 3084 */ 3085 FT_EXPORT( FT_Error ) 3086 FT_Request_Size( FT_Face face, 3087 FT_Size_Request req ); 3088 3089 3090 /************************************************************************** 3091 * 3092 * @function: 3093 * FT_Set_Char_Size 3094 * 3095 * @description: 3096 * Call @FT_Request_Size to request the nominal size (in points). 3097 * 3098 * @inout: 3099 * face :: 3100 * A handle to a target face object. 3101 * 3102 * @input: 3103 * char_width :: 3104 * The nominal width, in 26.6 fractional points. 3105 * 3106 * char_height :: 3107 * The nominal height, in 26.6 fractional points. 3108 * 3109 * horz_resolution :: 3110 * The horizontal resolution in dpi. 3111 * 3112 * vert_resolution :: 3113 * The vertical resolution in dpi. 3114 * 3115 * @return: 3116 * FreeType error code. 0~means success. 3117 * 3118 * @note: 3119 * While this function allows fractional points as input values, the 3120 * resulting ppem value for the given resolution is always rounded to the 3121 * nearest integer. 3122 * 3123 * If either the character width or height is zero, it is set equal to 3124 * the other value. 3125 * 3126 * If either the horizontal or vertical resolution is zero, it is set 3127 * equal to the other value. 3128 * 3129 * A character width or height smaller than 1pt is set to 1pt; if both 3130 * resolution values are zero, they are set to 72dpi. 3131 * 3132 * Don't use this function if you are using the FreeType cache API. 3133 */ 3134 FT_EXPORT( FT_Error ) 3135 FT_Set_Char_Size( FT_Face face, 3136 FT_F26Dot6 char_width, 3137 FT_F26Dot6 char_height, 3138 FT_UInt horz_resolution, 3139 FT_UInt vert_resolution ); 3140 3141 3142 /************************************************************************** 3143 * 3144 * @function: 3145 * FT_Set_Pixel_Sizes 3146 * 3147 * @description: 3148 * Call @FT_Request_Size to request the nominal size (in pixels). 3149 * 3150 * @inout: 3151 * face :: 3152 * A handle to the target face object. 3153 * 3154 * @input: 3155 * pixel_width :: 3156 * The nominal width, in pixels. 3157 * 3158 * pixel_height :: 3159 * The nominal height, in pixels. 3160 * 3161 * @return: 3162 * FreeType error code. 0~means success. 3163 * 3164 * @note: 3165 * You should not rely on the resulting glyphs matching or being 3166 * constrained to this pixel size. Refer to @FT_Request_Size to 3167 * understand how requested sizes relate to actual sizes. 3168 * 3169 * Don't use this function if you are using the FreeType cache API. 3170 */ 3171 FT_EXPORT( FT_Error ) 3172 FT_Set_Pixel_Sizes( FT_Face face, 3173 FT_UInt pixel_width, 3174 FT_UInt pixel_height ); 3175 3176 3177 /************************************************************************** 3178 * 3179 * @section: 3180 * glyph_retrieval 3181 * 3182 */ 3183 3184 /************************************************************************** 3185 * 3186 * @function: 3187 * FT_Load_Glyph 3188 * 3189 * @description: 3190 * Load a glyph into the glyph slot of a face object. 3191 * 3192 * @inout: 3193 * face :: 3194 * A handle to the target face object where the glyph is loaded. 3195 * 3196 * @input: 3197 * glyph_index :: 3198 * The index of the glyph in the font file. For CID-keyed fonts 3199 * (either in PS or in CFF format) this argument specifies the CID 3200 * value. 3201 * 3202 * load_flags :: 3203 * A flag indicating what to load for this glyph. The @FT_LOAD_XXX 3204 * flags can be used to control the glyph loading process (e.g., 3205 * whether the outline should be scaled, whether to load bitmaps or 3206 * not, whether to hint the outline, etc). 3207 * 3208 * @return: 3209 * FreeType error code. 0~means success. 3210 * 3211 * @note: 3212 * For proper scaling and hinting, the active @FT_Size object owned by 3213 * the face has to be meaningfully initialized by calling 3214 * @FT_Set_Char_Size before this function, for example. The loaded 3215 * glyph may be transformed. See @FT_Set_Transform for the details. 3216 * 3217 * For subsetted CID-keyed fonts, `FT_Err_Invalid_Argument` is returned 3218 * for invalid CID values (that is, for CID values that don't have a 3219 * corresponding glyph in the font). See the discussion of the 3220 * @FT_FACE_FLAG_CID_KEYED flag for more details. 3221 * 3222 * If you receive `FT_Err_Glyph_Too_Big`, try getting the glyph outline 3223 * at EM size, then scale it manually and fill it as a graphics 3224 * operation. 3225 */ 3226 FT_EXPORT( FT_Error ) 3227 FT_Load_Glyph( FT_Face face, 3228 FT_UInt glyph_index, 3229 FT_Int32 load_flags ); 3230 3231 3232 /************************************************************************** 3233 * 3234 * @section: 3235 * character_mapping 3236 * 3237 */ 3238 3239 /************************************************************************** 3240 * 3241 * @function: 3242 * FT_Load_Char 3243 * 3244 * @description: 3245 * Load a glyph into the glyph slot of a face object, accessed by its 3246 * character code. 3247 * 3248 * @inout: 3249 * face :: 3250 * A handle to a target face object where the glyph is loaded. 3251 * 3252 * @input: 3253 * char_code :: 3254 * The glyph's character code, according to the current charmap used in 3255 * the face. 3256 * 3257 * load_flags :: 3258 * A flag indicating what to load for this glyph. The @FT_LOAD_XXX 3259 * constants can be used to control the glyph loading process (e.g., 3260 * whether the outline should be scaled, whether to load bitmaps or 3261 * not, whether to hint the outline, etc). 3262 * 3263 * @return: 3264 * FreeType error code. 0~means success. 3265 * 3266 * @note: 3267 * This function simply calls @FT_Get_Char_Index and @FT_Load_Glyph. 3268 * 3269 * Many fonts contain glyphs that can't be loaded by this function since 3270 * its glyph indices are not listed in any of the font's charmaps. 3271 * 3272 * If no active cmap is set up (i.e., `face->charmap` is zero), the call 3273 * to @FT_Get_Char_Index is omitted, and the function behaves identically 3274 * to @FT_Load_Glyph. 3275 */ 3276 FT_EXPORT( FT_Error ) 3277 FT_Load_Char( FT_Face face, 3278 FT_ULong char_code, 3279 FT_Int32 load_flags ); 3280 3281 3282 /************************************************************************** 3283 * 3284 * @section: 3285 * glyph_retrieval 3286 * 3287 */ 3288 3289 /************************************************************************** 3290 * 3291 * @enum: 3292 * FT_LOAD_XXX 3293 * 3294 * @description: 3295 * A list of bit field constants for @FT_Load_Glyph to indicate what kind 3296 * of operations to perform during glyph loading. 3297 * 3298 * @values: 3299 * FT_LOAD_DEFAULT :: 3300 * Corresponding to~0, this value is used as the default glyph load 3301 * operation. In this case, the following happens: 3302 * 3303 * 1. FreeType looks for a bitmap for the glyph corresponding to the 3304 * face's current size. If one is found, the function returns. The 3305 * bitmap data can be accessed from the glyph slot (see note below). 3306 * 3307 * 2. If no embedded bitmap is searched for or found, FreeType looks 3308 * for a scalable outline. If one is found, it is loaded from the font 3309 * file, scaled to device pixels, then 'hinted' to the pixel grid in 3310 * order to optimize it. The outline data can be accessed from the 3311 * glyph slot (see note below). 3312 * 3313 * Note that by default the glyph loader doesn't render outlines into 3314 * bitmaps. The following flags are used to modify this default 3315 * behaviour to more specific and useful cases. 3316 * 3317 * FT_LOAD_NO_SCALE :: 3318 * Don't scale the loaded outline glyph but keep it in font units. 3319 * This flag is also assumed if @FT_Size owned by the face was not 3320 * properly initialized. 3321 * 3322 * This flag implies @FT_LOAD_NO_HINTING and @FT_LOAD_NO_BITMAP, and 3323 * unsets @FT_LOAD_RENDER. 3324 * 3325 * If the font is 'tricky' (see @FT_FACE_FLAG_TRICKY for more), using 3326 * `FT_LOAD_NO_SCALE` usually yields meaningless outlines because the 3327 * subglyphs must be scaled and positioned with hinting instructions. 3328 * This can be solved by loading the font without `FT_LOAD_NO_SCALE` 3329 * and setting the character size to `font->units_per_EM`. 3330 * 3331 * FT_LOAD_NO_HINTING :: 3332 * Disable hinting. This generally generates 'blurrier' bitmap glyphs 3333 * when the glyphs are rendered in any of the anti-aliased modes. See 3334 * also the note below. 3335 * 3336 * This flag is implied by @FT_LOAD_NO_SCALE. 3337 * 3338 * FT_LOAD_RENDER :: 3339 * Call @FT_Render_Glyph after the glyph is loaded. By default, the 3340 * glyph is rendered in @FT_RENDER_MODE_NORMAL mode. This can be 3341 * overridden by @FT_LOAD_TARGET_XXX or @FT_LOAD_MONOCHROME. 3342 * 3343 * This flag is unset by @FT_LOAD_NO_SCALE. 3344 * 3345 * FT_LOAD_NO_BITMAP :: 3346 * Ignore bitmap strikes when loading. Bitmap-only fonts ignore this 3347 * flag. 3348 * 3349 * @FT_LOAD_NO_SCALE always sets this flag. 3350 * 3351 * FT_LOAD_SBITS_ONLY :: 3352 * [Since 2.12] This is the opposite of @FT_LOAD_NO_BITMAP, more or 3353 * less: @FT_Load_Glyph returns `FT_Err_Invalid_Argument` if the face 3354 * contains a bitmap strike for the given size (or the strike selected 3355 * by @FT_Select_Size) but there is no glyph in the strike. 3356 * 3357 * Note that this load flag was part of FreeType since version 2.0.6 3358 * but previously tagged as internal. 3359 * 3360 * FT_LOAD_VERTICAL_LAYOUT :: 3361 * Load the glyph for vertical text layout. In particular, the 3362 * `advance` value in the @FT_GlyphSlotRec structure is set to the 3363 * `vertAdvance` value of the `metrics` field. 3364 * 3365 * In case @FT_HAS_VERTICAL doesn't return true, you shouldn't use this 3366 * flag currently. Reason is that in this case vertical metrics get 3367 * synthesized, and those values are not always consistent across 3368 * various font formats. 3369 * 3370 * FT_LOAD_FORCE_AUTOHINT :: 3371 * Prefer the auto-hinter over the font's native hinter. See also the 3372 * note below. 3373 * 3374 * FT_LOAD_PEDANTIC :: 3375 * Make the font driver perform pedantic verifications during glyph 3376 * loading and hinting. This is mostly used to detect broken glyphs in 3377 * fonts. By default, FreeType tries to handle broken fonts also. 3378 * 3379 * In particular, errors from the TrueType bytecode engine are not 3380 * passed to the application if this flag is not set; this might result 3381 * in partially hinted or distorted glyphs in case a glyph's bytecode 3382 * is buggy. 3383 * 3384 * FT_LOAD_NO_RECURSE :: 3385 * Don't load composite glyphs recursively. Instead, the font driver 3386 * fills the `num_subglyph` and `subglyphs` values of the glyph slot; 3387 * it also sets `glyph->format` to @FT_GLYPH_FORMAT_COMPOSITE. The 3388 * description of subglyphs can then be accessed with 3389 * @FT_Get_SubGlyph_Info. 3390 * 3391 * Don't use this flag for retrieving metrics information since some 3392 * font drivers only return rudimentary data. 3393 * 3394 * This flag implies @FT_LOAD_NO_SCALE and @FT_LOAD_IGNORE_TRANSFORM. 3395 * 3396 * FT_LOAD_IGNORE_TRANSFORM :: 3397 * Ignore the transform matrix set by @FT_Set_Transform. 3398 * 3399 * FT_LOAD_MONOCHROME :: 3400 * This flag is used with @FT_LOAD_RENDER to indicate that you want to 3401 * render an outline glyph to a 1-bit monochrome bitmap glyph, with 3402 * 8~pixels packed into each byte of the bitmap data. 3403 * 3404 * Note that this has no effect on the hinting algorithm used. You 3405 * should rather use @FT_LOAD_TARGET_MONO so that the 3406 * monochrome-optimized hinting algorithm is used. 3407 * 3408 * FT_LOAD_LINEAR_DESIGN :: 3409 * Keep `linearHoriAdvance` and `linearVertAdvance` fields of 3410 * @FT_GlyphSlotRec in font units. See @FT_GlyphSlotRec for details. 3411 * 3412 * FT_LOAD_NO_AUTOHINT :: 3413 * Disable the auto-hinter. See also the note below. 3414 * 3415 * FT_LOAD_COLOR :: 3416 * Load colored glyphs. FreeType searches in the following order; 3417 * there are slight differences depending on the font format. 3418 * 3419 * [Since 2.5] Load embedded color bitmap images (provided 3420 * @FT_LOAD_NO_BITMAP is not set). The resulting color bitmaps, if 3421 * available, have the @FT_PIXEL_MODE_BGRA format, with pre-multiplied 3422 * color channels. If the flag is not set and color bitmaps are found, 3423 * they are converted to 256-level gray bitmaps, using the 3424 * @FT_PIXEL_MODE_GRAY format. 3425 * 3426 * [Since 2.12] If the glyph index maps to an entry in the face's 3427 * 'SVG~' table, load the associated SVG document from this table and 3428 * set the `format` field of @FT_GlyphSlotRec to @FT_GLYPH_FORMAT_SVG 3429 * ([since 2.13.1] provided @FT_LOAD_NO_SVG is not set). Note that 3430 * FreeType itself can't render SVG documents; however, the library 3431 * provides hooks to seamlessly integrate an external renderer. See 3432 * sections @ot_svg_driver and @svg_fonts for more. 3433 * 3434 * [Since 2.10, experimental] If the glyph index maps to an entry in 3435 * the face's 'COLR' table with a 'CPAL' palette table (as defined in 3436 * the OpenType specification), make @FT_Render_Glyph provide a default 3437 * blending of the color glyph layers associated with the glyph index, 3438 * using the same bitmap format as embedded color bitmap images. This 3439 * is mainly for convenience and works only for glyphs in 'COLR' v0 3440 * tables (or glyphs in 'COLR' v1 tables that exclusively use v0 3441 * features). For full control of color layers use 3442 * @FT_Get_Color_Glyph_Layer and FreeType's color functions like 3443 * @FT_Palette_Select instead of setting @FT_LOAD_COLOR for rendering 3444 * so that the client application can handle blending by itself. 3445 * 3446 * FT_LOAD_NO_SVG :: 3447 * [Since 2.13.1] Ignore SVG glyph data when loading. 3448 * 3449 * FT_LOAD_COMPUTE_METRICS :: 3450 * [Since 2.6.1] Compute glyph metrics from the glyph data, without the 3451 * use of bundled metrics tables (for example, the 'hdmx' table in 3452 * TrueType fonts). This flag is mainly used by font validating or 3453 * font editing applications, which need to ignore, verify, or edit 3454 * those tables. 3455 * 3456 * Currently, this flag is only implemented for TrueType fonts. 3457 * 3458 * FT_LOAD_BITMAP_METRICS_ONLY :: 3459 * [Since 2.7.1] Request loading of the metrics and bitmap image 3460 * information of a (possibly embedded) bitmap glyph without allocating 3461 * or copying the bitmap image data itself. No effect if the target 3462 * glyph is not a bitmap image. 3463 * 3464 * This flag unsets @FT_LOAD_RENDER. 3465 * 3466 * FT_LOAD_CROP_BITMAP :: 3467 * Ignored. Deprecated. 3468 * 3469 * FT_LOAD_IGNORE_GLOBAL_ADVANCE_WIDTH :: 3470 * Ignored. Deprecated. 3471 * 3472 * @note: 3473 * By default, hinting is enabled and the font's native hinter (see 3474 * @FT_FACE_FLAG_HINTER) is preferred over the auto-hinter. You can 3475 * disable hinting by setting @FT_LOAD_NO_HINTING or change the 3476 * precedence by setting @FT_LOAD_FORCE_AUTOHINT. You can also set 3477 * @FT_LOAD_NO_AUTOHINT in case you don't want the auto-hinter to be used 3478 * at all. 3479 * 3480 * See the description of @FT_FACE_FLAG_TRICKY for a special exception 3481 * (affecting only a handful of Asian fonts). 3482 * 3483 * Besides deciding which hinter to use, you can also decide which 3484 * hinting algorithm to use. See @FT_LOAD_TARGET_XXX for details. 3485 * 3486 * Note that the auto-hinter needs a valid Unicode cmap (either a native 3487 * one or synthesized by FreeType) for producing correct results. If a 3488 * font provides an incorrect mapping (for example, assigning the 3489 * character code U+005A, LATIN CAPITAL LETTER~Z, to a glyph depicting a 3490 * mathematical integral sign), the auto-hinter might produce useless 3491 * results. 3492 * 3493 */ 3494 #define FT_LOAD_DEFAULT 0x0 3495 #define FT_LOAD_NO_SCALE ( 1L << 0 ) 3496 #define FT_LOAD_NO_HINTING ( 1L << 1 ) 3497 #define FT_LOAD_RENDER ( 1L << 2 ) 3498 #define FT_LOAD_NO_BITMAP ( 1L << 3 ) 3499 #define FT_LOAD_VERTICAL_LAYOUT ( 1L << 4 ) 3500 #define FT_LOAD_FORCE_AUTOHINT ( 1L << 5 ) 3501 #define FT_LOAD_CROP_BITMAP ( 1L << 6 ) 3502 #define FT_LOAD_PEDANTIC ( 1L << 7 ) 3503 #define FT_LOAD_IGNORE_GLOBAL_ADVANCE_WIDTH ( 1L << 9 ) 3504 #define FT_LOAD_NO_RECURSE ( 1L << 10 ) 3505 #define FT_LOAD_IGNORE_TRANSFORM ( 1L << 11 ) 3506 #define FT_LOAD_MONOCHROME ( 1L << 12 ) 3507 #define FT_LOAD_LINEAR_DESIGN ( 1L << 13 ) 3508 #define FT_LOAD_SBITS_ONLY ( 1L << 14 ) 3509 #define FT_LOAD_NO_AUTOHINT ( 1L << 15 ) 3510 /* Bits 16-19 are used by `FT_LOAD_TARGET_` */ 3511 #define FT_LOAD_COLOR ( 1L << 20 ) 3512 #define FT_LOAD_COMPUTE_METRICS ( 1L << 21 ) 3513 #define FT_LOAD_BITMAP_METRICS_ONLY ( 1L << 22 ) 3514 #define FT_LOAD_NO_SVG ( 1L << 24 ) 3515 3516 /* */ 3517 3518 /* used internally only by certain font drivers */ 3519 #define FT_LOAD_ADVANCE_ONLY ( 1L << 8 ) 3520 #define FT_LOAD_SVG_ONLY ( 1L << 23 ) 3521 3522 3523 /************************************************************************** 3524 * 3525 * @enum: 3526 * FT_LOAD_TARGET_XXX 3527 * 3528 * @description: 3529 * A list of values to select a specific hinting algorithm for the 3530 * hinter. You should OR one of these values to your `load_flags` when 3531 * calling @FT_Load_Glyph. 3532 * 3533 * Note that a font's native hinters may ignore the hinting algorithm you 3534 * have specified (e.g., the TrueType bytecode interpreter). You can set 3535 * @FT_LOAD_FORCE_AUTOHINT to ensure that the auto-hinter is used. 3536 * 3537 * @values: 3538 * FT_LOAD_TARGET_NORMAL :: 3539 * The default hinting algorithm, optimized for standard gray-level 3540 * rendering. For monochrome output, use @FT_LOAD_TARGET_MONO instead. 3541 * 3542 * FT_LOAD_TARGET_LIGHT :: 3543 * A lighter hinting algorithm for gray-level modes. Many generated 3544 * glyphs are fuzzier but better resemble their original shape. This 3545 * is achieved by snapping glyphs to the pixel grid only vertically 3546 * (Y-axis), as is done by FreeType's new CFF engine or Microsoft's 3547 * ClearType font renderer. This preserves inter-glyph spacing in 3548 * horizontal text. The snapping is done either by the native font 3549 * driver, if the driver itself and the font support it, or by the 3550 * auto-hinter. 3551 * 3552 * Advance widths are rounded to integer values; however, using the 3553 * `lsb_delta` and `rsb_delta` fields of @FT_GlyphSlotRec, it is 3554 * possible to get fractional advance widths for subpixel positioning 3555 * (which is recommended to use). 3556 * 3557 * If configuration option `AF_CONFIG_OPTION_TT_SIZE_METRICS` is 3558 * active, TrueType-like metrics are used to make this mode behave 3559 * similarly as in unpatched FreeType versions between 2.4.6 and 2.7.1 3560 * (inclusive). 3561 * 3562 * FT_LOAD_TARGET_MONO :: 3563 * Strong hinting algorithm that should only be used for monochrome 3564 * output. The result is probably unpleasant if the glyph is rendered 3565 * in non-monochrome modes. 3566 * 3567 * Note that for outline fonts only the TrueType font driver has proper 3568 * monochrome hinting support, provided the TTFs contain hints for B/W 3569 * rendering (which most fonts no longer provide). If these conditions 3570 * are not met it is very likely that you get ugly results at smaller 3571 * sizes. 3572 * 3573 * FT_LOAD_TARGET_LCD :: 3574 * A variant of @FT_LOAD_TARGET_LIGHT optimized for horizontally 3575 * decimated LCD displays. 3576 * 3577 * FT_LOAD_TARGET_LCD_V :: 3578 * A variant of @FT_LOAD_TARGET_NORMAL optimized for vertically 3579 * decimated LCD displays. 3580 * 3581 * @note: 3582 * You should use only _one_ of the `FT_LOAD_TARGET_XXX` values in your 3583 * `load_flags`. They can't be ORed. 3584 * 3585 * If @FT_LOAD_RENDER is also set, the glyph is rendered in the 3586 * corresponding mode (i.e., the mode that matches the used algorithm 3587 * best). An exception is `FT_LOAD_TARGET_MONO` since it implies 3588 * @FT_LOAD_MONOCHROME. 3589 * 3590 * You can use a hinting algorithm that doesn't correspond to the same 3591 * rendering mode. As an example, it is possible to use the 'light' 3592 * hinting algorithm and have the results rendered in horizontal LCD 3593 * pixel mode, with code like 3594 * 3595 * ``` 3596 * FT_Load_Glyph( face, glyph_index, 3597 * load_flags | FT_LOAD_TARGET_LIGHT ); 3598 * 3599 * FT_Render_Glyph( face->glyph, FT_RENDER_MODE_LCD ); 3600 * ``` 3601 * 3602 * In general, you should stick with one rendering mode. For example, 3603 * switching between @FT_LOAD_TARGET_NORMAL and @FT_LOAD_TARGET_MONO 3604 * enforces a lot of recomputation for TrueType fonts, which is slow. 3605 * Another reason is caching: Selecting a different mode usually causes 3606 * changes in both the outlines and the rasterized bitmaps; it is thus 3607 * necessary to empty the cache after a mode switch to avoid false hits. 3608 * 3609 */ 3610 #define FT_LOAD_TARGET_( x ) ( FT_STATIC_CAST( FT_Int32, (x) & 15 ) << 16 ) 3611 3612 #define FT_LOAD_TARGET_NORMAL FT_LOAD_TARGET_( FT_RENDER_MODE_NORMAL ) 3613 #define FT_LOAD_TARGET_LIGHT FT_LOAD_TARGET_( FT_RENDER_MODE_LIGHT ) 3614 #define FT_LOAD_TARGET_MONO FT_LOAD_TARGET_( FT_RENDER_MODE_MONO ) 3615 #define FT_LOAD_TARGET_LCD FT_LOAD_TARGET_( FT_RENDER_MODE_LCD ) 3616 #define FT_LOAD_TARGET_LCD_V FT_LOAD_TARGET_( FT_RENDER_MODE_LCD_V ) 3617 3618 3619 /************************************************************************** 3620 * 3621 * @macro: 3622 * FT_LOAD_TARGET_MODE 3623 * 3624 * @description: 3625 * Return the @FT_Render_Mode corresponding to a given 3626 * @FT_LOAD_TARGET_XXX value. 3627 * 3628 */ 3629 #define FT_LOAD_TARGET_MODE( x ) \ 3630 FT_STATIC_CAST( FT_Render_Mode, ( (x) >> 16 ) & 15 ) 3631 3632 3633 /************************************************************************** 3634 * 3635 * @section: 3636 * sizing_and_scaling 3637 * 3638 */ 3639 3640 /************************************************************************** 3641 * 3642 * @function: 3643 * FT_Set_Transform 3644 * 3645 * @description: 3646 * Set the transformation that is applied to glyph images when they are 3647 * loaded into a glyph slot through @FT_Load_Glyph. 3648 * 3649 * @inout: 3650 * face :: 3651 * A handle to the source face object. 3652 * 3653 * @input: 3654 * matrix :: 3655 * A pointer to the transformation's 2x2 matrix. Use `NULL` for the 3656 * identity matrix. 3657 * delta :: 3658 * A pointer to the translation vector. Use `NULL` for the null 3659 * vector. 3660 * 3661 * @note: 3662 * This function is provided as a convenience, but keep in mind that 3663 * @FT_Matrix coefficients are only 16.16 fixed-point values, which can 3664 * limit the accuracy of the results. Using floating-point computations 3665 * to perform the transform directly in client code instead will always 3666 * yield better numbers. 3667 * 3668 * The transformation is only applied to scalable image formats after the 3669 * glyph has been loaded. It means that hinting is unaltered by the 3670 * transformation and is performed on the character size given in the 3671 * last call to @FT_Set_Char_Size or @FT_Set_Pixel_Sizes. 3672 * 3673 * Note that this also transforms the `face.glyph.advance` field, but 3674 * **not** the values in `face.glyph.metrics`. 3675 */ 3676 FT_EXPORT( void ) 3677 FT_Set_Transform( FT_Face face, 3678 FT_Matrix* matrix, 3679 FT_Vector* delta ); 3680 3681 3682 /************************************************************************** 3683 * 3684 * @function: 3685 * FT_Get_Transform 3686 * 3687 * @description: 3688 * Return the transformation that is applied to glyph images when they 3689 * are loaded into a glyph slot through @FT_Load_Glyph. See 3690 * @FT_Set_Transform for more details. 3691 * 3692 * @input: 3693 * face :: 3694 * A handle to the source face object. 3695 * 3696 * @output: 3697 * matrix :: 3698 * A pointer to a transformation's 2x2 matrix. Set this to NULL if you 3699 * are not interested in the value. 3700 * 3701 * delta :: 3702 * A pointer to a translation vector. Set this to NULL if you are not 3703 * interested in the value. 3704 * 3705 * @since: 3706 * 2.11 3707 * 3708 */ 3709 FT_EXPORT( void ) 3710 FT_Get_Transform( FT_Face face, 3711 FT_Matrix* matrix, 3712 FT_Vector* delta ); 3713 3714 3715 /************************************************************************** 3716 * 3717 * @section: 3718 * glyph_retrieval 3719 * 3720 */ 3721 3722 /************************************************************************** 3723 * 3724 * @enum: 3725 * FT_Render_Mode 3726 * 3727 * @description: 3728 * Render modes supported by FreeType~2. Each mode corresponds to a 3729 * specific type of scanline conversion performed on the outline. 3730 * 3731 * For bitmap fonts and embedded bitmaps the `bitmap->pixel_mode` field 3732 * in the @FT_GlyphSlotRec structure gives the format of the returned 3733 * bitmap. 3734 * 3735 * All modes except @FT_RENDER_MODE_MONO use 256 levels of opacity, 3736 * indicating pixel coverage. Use linear alpha blending and gamma 3737 * correction to correctly render non-monochrome glyph bitmaps onto a 3738 * surface; see @FT_Render_Glyph. 3739 * 3740 * The @FT_RENDER_MODE_SDF is a special render mode that uses up to 256 3741 * distance values, indicating the signed distance from the grid position 3742 * to the nearest outline. 3743 * 3744 * @values: 3745 * FT_RENDER_MODE_NORMAL :: 3746 * Default render mode; it corresponds to 8-bit anti-aliased bitmaps. 3747 * 3748 * FT_RENDER_MODE_LIGHT :: 3749 * This is equivalent to @FT_RENDER_MODE_NORMAL. It is only defined as 3750 * a separate value because render modes are also used indirectly to 3751 * define hinting algorithm selectors. See @FT_LOAD_TARGET_XXX for 3752 * details. 3753 * 3754 * FT_RENDER_MODE_MONO :: 3755 * This mode corresponds to 1-bit bitmaps (with 2~levels of opacity). 3756 * 3757 * FT_RENDER_MODE_LCD :: 3758 * This mode corresponds to horizontal RGB and BGR subpixel displays 3759 * like LCD screens. It produces 8-bit bitmaps that are 3~times the 3760 * width of the original glyph outline in pixels, and which use the 3761 * @FT_PIXEL_MODE_LCD mode. 3762 * 3763 * FT_RENDER_MODE_LCD_V :: 3764 * This mode corresponds to vertical RGB and BGR subpixel displays 3765 * (like PDA screens, rotated LCD displays, etc.). It produces 8-bit 3766 * bitmaps that are 3~times the height of the original glyph outline in 3767 * pixels and use the @FT_PIXEL_MODE_LCD_V mode. 3768 * 3769 * FT_RENDER_MODE_SDF :: 3770 * This mode corresponds to 8-bit, single-channel signed distance field 3771 * (SDF) bitmaps. Each pixel in the SDF grid is the value from the 3772 * pixel's position to the nearest glyph's outline. The distances are 3773 * calculated from the center of the pixel and are positive if they are 3774 * filled by the outline (i.e., inside the outline) and negative 3775 * otherwise. Check the note below on how to convert the output values 3776 * to usable data. 3777 * 3778 * @note: 3779 * The selected render mode only affects vector glyphs of a font. 3780 * Embedded bitmaps often have a different pixel mode like 3781 * @FT_PIXEL_MODE_MONO. You can use @FT_Bitmap_Convert to transform them 3782 * into 8-bit pixmaps. 3783 * 3784 * For @FT_RENDER_MODE_SDF the output bitmap buffer contains normalized 3785 * distances that are packed into unsigned 8-bit values. To get pixel 3786 * values in floating point representation use the following pseudo-C 3787 * code for the conversion. 3788 * 3789 * ``` 3790 * // Load glyph and render using FT_RENDER_MODE_SDF, 3791 * // then use the output buffer as follows. 3792 * 3793 * ... 3794 * FT_Byte buffer = glyph->bitmap->buffer; 3795 * 3796 * 3797 * for pixel in buffer 3798 * { 3799 * // `sd` is the signed distance and `spread` is the current spread; 3800 * // the default spread is 2 and can be changed. 3801 * 3802 * float sd = (float)pixel - 128.0f; 3803 * 3804 * 3805 * // Convert to pixel values. 3806 * sd = ( sd / 128.0f ) * spread; 3807 * 3808 * // Store `sd` in a buffer or use as required. 3809 * } 3810 * 3811 * ``` 3812 * 3813 * FreeType has two rasterizers for generating SDF, namely: 3814 * 3815 * 1. `sdf` for generating SDF directly from glyph's outline, and 3816 * 3817 * 2. `bsdf` for generating SDF from rasterized bitmaps. 3818 * 3819 * Depending on the glyph type (i.e., outline or bitmap), one of the two 3820 * rasterizers is chosen at runtime and used for generating SDFs. To 3821 * force the use of `bsdf` you should render the glyph with any of the 3822 * FreeType's other rendering modes (e.g., `FT_RENDER_MODE_NORMAL`) and 3823 * then re-render with `FT_RENDER_MODE_SDF`. 3824 * 3825 * There are some issues with stability and possible failures of the SDF 3826 * renderers (specifically `sdf`). 3827 * 3828 * 1. The `sdf` rasterizer is sensitive to really small features (e.g., 3829 * sharp turns that are less than 1~pixel) and imperfections in the 3830 * glyph's outline, causing artifacts in the final output. 3831 * 3832 * 2. The `sdf` rasterizer has limited support for handling intersecting 3833 * contours and *cannot* handle self-intersecting contours whatsoever. 3834 * Self-intersection happens when a single connected contour 3835 * intersects itself at some point; having these in your font 3836 * definitely poses a problem to the rasterizer and cause artifacts, 3837 * too. 3838 * 3839 * 3. Generating SDF for really small glyphs may result in undesirable 3840 * output; the pixel grid (which stores distance information) becomes 3841 * too coarse. 3842 * 3843 * 4. Since the output buffer is normalized, precision at smaller spreads 3844 * is greater than precision at larger spread values because the 3845 * output range of [0..255] gets mapped to a smaller SDF range. A 3846 * spread of~2 should be sufficient in most cases. 3847 * 3848 * Points (1) and (2) can be avoided by using the `bsdf` rasterizer, 3849 * which is more stable than the `sdf` rasterizer in general. 3850 * 3851 */ 3852 typedef enum FT_Render_Mode_ 3853 { 3854 FT_RENDER_MODE_NORMAL = 0, 3855 FT_RENDER_MODE_LIGHT, 3856 FT_RENDER_MODE_MONO, 3857 FT_RENDER_MODE_LCD, 3858 FT_RENDER_MODE_LCD_V, 3859 FT_RENDER_MODE_SDF, 3860 3861 FT_RENDER_MODE_MAX 3862 3863 } FT_Render_Mode; 3864 3865 3866 /* these constants are deprecated; use the corresponding */ 3867 /* `FT_Render_Mode` values instead */ 3868 #define ft_render_mode_normal FT_RENDER_MODE_NORMAL 3869 #define ft_render_mode_mono FT_RENDER_MODE_MONO 3870 3871 3872 /************************************************************************** 3873 * 3874 * @function: 3875 * FT_Render_Glyph 3876 * 3877 * @description: 3878 * Convert a given glyph image to a bitmap. It does so by inspecting the 3879 * glyph image format, finding the relevant renderer, and invoking it. 3880 * 3881 * @inout: 3882 * slot :: 3883 * A handle to the glyph slot containing the image to convert. 3884 * 3885 * @input: 3886 * render_mode :: 3887 * The render mode used to render the glyph image into a bitmap. See 3888 * @FT_Render_Mode for a list of possible values. 3889 * 3890 * If @FT_RENDER_MODE_NORMAL is used, a previous call of @FT_Load_Glyph 3891 * with flag @FT_LOAD_COLOR makes `FT_Render_Glyph` provide a default 3892 * blending of colored glyph layers associated with the current glyph 3893 * slot (provided the font contains such layers) instead of rendering 3894 * the glyph slot's outline. This is an experimental feature; see 3895 * @FT_LOAD_COLOR for more information. 3896 * 3897 * @return: 3898 * FreeType error code. 0~means success. 3899 * 3900 * @note: 3901 * When FreeType outputs a bitmap of a glyph, it really outputs an alpha 3902 * coverage map. If a pixel is completely covered by a filled-in 3903 * outline, the bitmap contains 0xFF at that pixel, meaning that 3904 * 0xFF/0xFF fraction of that pixel is covered, meaning the pixel is 100% 3905 * black (or 0% bright). If a pixel is only 50% covered (value 0x80), 3906 * the pixel is made 50% black (50% bright or a middle shade of grey). 3907 * 0% covered means 0% black (100% bright or white). 3908 * 3909 * On high-DPI screens like on smartphones and tablets, the pixels are so 3910 * small that their chance of being completely covered and therefore 3911 * completely black are fairly good. On the low-DPI screens, however, 3912 * the situation is different. The pixels are too large for most of the 3913 * details of a glyph and shades of gray are the norm rather than the 3914 * exception. 3915 * 3916 * This is relevant because all our screens have a second problem: they 3917 * are not linear. 1~+~1 is not~2. Twice the value does not result in 3918 * twice the brightness. When a pixel is only 50% covered, the coverage 3919 * map says 50% black, and this translates to a pixel value of 128 when 3920 * you use 8~bits per channel (0-255). However, this does not translate 3921 * to 50% brightness for that pixel on our sRGB and gamma~2.2 screens. 3922 * Due to their non-linearity, they dwell longer in the darks and only a 3923 * pixel value of about 186 results in 50% brightness -- 128 ends up too 3924 * dark on both bright and dark backgrounds. The net result is that dark 3925 * text looks burnt-out, pixely and blotchy on bright background, bright 3926 * text too frail on dark backgrounds, and colored text on colored 3927 * background (for example, red on green) seems to have dark halos or 3928 * 'dirt' around it. The situation is especially ugly for diagonal stems 3929 * like in 'w' glyph shapes where the quality of FreeType's anti-aliasing 3930 * depends on the correct display of grays. On high-DPI screens where 3931 * smaller, fully black pixels reign supreme, this doesn't matter, but on 3932 * our low-DPI screens with all the gray shades, it does. 0% and 100% 3933 * brightness are the same things in linear and non-linear space, just 3934 * all the shades in-between aren't. 3935 * 3936 * The blending function for placing text over a background is 3937 * 3938 * ``` 3939 * dst = alpha * src + (1 - alpha) * dst , 3940 * ``` 3941 * 3942 * which is known as the OVER operator. 3943 * 3944 * To correctly composite an anti-aliased pixel of a glyph onto a 3945 * surface, 3946 * 3947 * 1. take the foreground and background colors (e.g., in sRGB space) 3948 * and apply gamma to get them in a linear space, 3949 * 3950 * 2. use OVER to blend the two linear colors using the glyph pixel 3951 * as the alpha value (remember, the glyph bitmap is an alpha coverage 3952 * bitmap), and 3953 * 3954 * 3. apply inverse gamma to the blended pixel and write it back to 3955 * the image. 3956 * 3957 * Internal testing at Adobe found that a target inverse gamma of~1.8 for 3958 * step~3 gives good results across a wide range of displays with an sRGB 3959 * gamma curve or a similar one. 3960 * 3961 * This process can cost performance. There is an approximation that 3962 * does not need to know about the background color; see 3963 * https://bel.fi/alankila/lcd/ and 3964 * https://bel.fi/alankila/lcd/alpcor.html for details. 3965 * 3966 * **ATTENTION**: Linear blending is even more important when dealing 3967 * with subpixel-rendered glyphs to prevent color-fringing! A 3968 * subpixel-rendered glyph must first be filtered with a filter that 3969 * gives equal weight to the three color primaries and does not exceed a 3970 * sum of 0x100, see section @lcd_rendering. Then the only difference to 3971 * gray linear blending is that subpixel-rendered linear blending is done 3972 * 3~times per pixel: red foreground subpixel to red background subpixel 3973 * and so on for green and blue. 3974 */ 3975 FT_EXPORT( FT_Error ) 3976 FT_Render_Glyph( FT_GlyphSlot slot, 3977 FT_Render_Mode render_mode ); 3978 3979 3980 /************************************************************************** 3981 * 3982 * @enum: 3983 * FT_Kerning_Mode 3984 * 3985 * @description: 3986 * An enumeration to specify the format of kerning values returned by 3987 * @FT_Get_Kerning. 3988 * 3989 * @values: 3990 * FT_KERNING_DEFAULT :: 3991 * Return grid-fitted kerning distances in 26.6 fractional pixels. 3992 * 3993 * FT_KERNING_UNFITTED :: 3994 * Return un-grid-fitted kerning distances in 26.6 fractional pixels. 3995 * 3996 * FT_KERNING_UNSCALED :: 3997 * Return the kerning vector in original font units. 3998 * 3999 * @note: 4000 * `FT_KERNING_DEFAULT` returns full pixel values; it also makes FreeType 4001 * heuristically scale down kerning distances at small ppem values so 4002 * that they don't become too big. 4003 * 4004 * Both `FT_KERNING_DEFAULT` and `FT_KERNING_UNFITTED` use the current 4005 * horizontal scaling factor (as set e.g. with @FT_Set_Char_Size) to 4006 * convert font units to pixels. 4007 */ 4008 typedef enum FT_Kerning_Mode_ 4009 { 4010 FT_KERNING_DEFAULT = 0, 4011 FT_KERNING_UNFITTED, 4012 FT_KERNING_UNSCALED 4013 4014 } FT_Kerning_Mode; 4015 4016 4017 /* these constants are deprecated; use the corresponding */ 4018 /* `FT_Kerning_Mode` values instead */ 4019 #define ft_kerning_default FT_KERNING_DEFAULT 4020 #define ft_kerning_unfitted FT_KERNING_UNFITTED 4021 #define ft_kerning_unscaled FT_KERNING_UNSCALED 4022 4023 4024 /************************************************************************** 4025 * 4026 * @function: 4027 * FT_Get_Kerning 4028 * 4029 * @description: 4030 * Return the kerning vector between two glyphs of the same face. 4031 * 4032 * @input: 4033 * face :: 4034 * A handle to a source face object. 4035 * 4036 * left_glyph :: 4037 * The index of the left glyph in the kern pair. 4038 * 4039 * right_glyph :: 4040 * The index of the right glyph in the kern pair. 4041 * 4042 * kern_mode :: 4043 * See @FT_Kerning_Mode for more information. Determines the scale and 4044 * dimension of the returned kerning vector. 4045 * 4046 * @output: 4047 * akerning :: 4048 * The kerning vector. This is either in font units, fractional pixels 4049 * (26.6 format), or pixels for scalable formats, and in pixels for 4050 * fixed-sizes formats. 4051 * 4052 * @return: 4053 * FreeType error code. 0~means success. 4054 * 4055 * @note: 4056 * Only horizontal layouts (left-to-right & right-to-left) are supported 4057 * by this method. Other layouts, or more sophisticated kernings, are 4058 * out of the scope of this API function -- they can be implemented 4059 * through format-specific interfaces. 4060 * 4061 * Kerning for OpenType fonts implemented in a 'GPOS' table is not 4062 * supported; use @FT_HAS_KERNING to find out whether a font has data 4063 * that can be extracted with `FT_Get_Kerning`. 4064 */ 4065 FT_EXPORT( FT_Error ) 4066 FT_Get_Kerning( FT_Face face, 4067 FT_UInt left_glyph, 4068 FT_UInt right_glyph, 4069 FT_UInt kern_mode, 4070 FT_Vector *akerning ); 4071 4072 4073 /************************************************************************** 4074 * 4075 * @function: 4076 * FT_Get_Track_Kerning 4077 * 4078 * @description: 4079 * Return the track kerning for a given face object at a given size. 4080 * 4081 * @input: 4082 * face :: 4083 * A handle to a source face object. 4084 * 4085 * point_size :: 4086 * The point size in 16.16 fractional points. 4087 * 4088 * degree :: 4089 * The degree of tightness. Increasingly negative values represent 4090 * tighter track kerning, while increasingly positive values represent 4091 * looser track kerning. Value zero means no track kerning. 4092 * 4093 * @output: 4094 * akerning :: 4095 * The kerning in 16.16 fractional points, to be uniformly applied 4096 * between all glyphs. 4097 * 4098 * @return: 4099 * FreeType error code. 0~means success. 4100 * 4101 * @note: 4102 * Currently, only the Type~1 font driver supports track kerning, using 4103 * data from AFM files (if attached with @FT_Attach_File or 4104 * @FT_Attach_Stream). 4105 * 4106 * Only very few AFM files come with track kerning data; please refer to 4107 * Adobe's AFM specification for more details. 4108 */ 4109 FT_EXPORT( FT_Error ) 4110 FT_Get_Track_Kerning( FT_Face face, 4111 FT_Fixed point_size, 4112 FT_Int degree, 4113 FT_Fixed* akerning ); 4114 4115 4116 /************************************************************************** 4117 * 4118 * @section: 4119 * character_mapping 4120 * 4121 */ 4122 4123 /************************************************************************** 4124 * 4125 * @function: 4126 * FT_Select_Charmap 4127 * 4128 * @description: 4129 * Select a given charmap by its encoding tag (as listed in 4130 * `freetype.h`). 4131 * 4132 * @inout: 4133 * face :: 4134 * A handle to the source face object. 4135 * 4136 * @input: 4137 * encoding :: 4138 * A handle to the selected encoding. 4139 * 4140 * @return: 4141 * FreeType error code. 0~means success. 4142 * 4143 * @note: 4144 * This function returns an error if no charmap in the face corresponds 4145 * to the encoding queried here. 4146 * 4147 * Because many fonts contain more than a single cmap for Unicode 4148 * encoding, this function has some special code to select the one that 4149 * covers Unicode best ('best' in the sense that a UCS-4 cmap is 4150 * preferred to a UCS-2 cmap). It is thus preferable to @FT_Set_Charmap 4151 * in this case. 4152 */ 4153 FT_EXPORT( FT_Error ) 4154 FT_Select_Charmap( FT_Face face, 4155 FT_Encoding encoding ); 4156 4157 4158 /************************************************************************** 4159 * 4160 * @function: 4161 * FT_Set_Charmap 4162 * 4163 * @description: 4164 * Select a given charmap for character code to glyph index mapping. 4165 * 4166 * @inout: 4167 * face :: 4168 * A handle to the source face object. 4169 * 4170 * @input: 4171 * charmap :: 4172 * A handle to the selected charmap. 4173 * 4174 * @return: 4175 * FreeType error code. 0~means success. 4176 * 4177 * @note: 4178 * This function returns an error if the charmap is not part of the face 4179 * (i.e., if it is not listed in the `face->charmaps` table). 4180 * 4181 * It also fails if an OpenType type~14 charmap is selected (which 4182 * doesn't map character codes to glyph indices at all). 4183 */ 4184 FT_EXPORT( FT_Error ) 4185 FT_Set_Charmap( FT_Face face, 4186 FT_CharMap charmap ); 4187 4188 4189 /************************************************************************** 4190 * 4191 * @function: 4192 * FT_Get_Charmap_Index 4193 * 4194 * @description: 4195 * Retrieve index of a given charmap. 4196 * 4197 * @input: 4198 * charmap :: 4199 * A handle to a charmap. 4200 * 4201 * @return: 4202 * The index into the array of character maps within the face to which 4203 * `charmap` belongs. If an error occurs, -1 is returned. 4204 * 4205 */ 4206 FT_EXPORT( FT_Int ) 4207 FT_Get_Charmap_Index( FT_CharMap charmap ); 4208 4209 4210 /************************************************************************** 4211 * 4212 * @function: 4213 * FT_Get_Char_Index 4214 * 4215 * @description: 4216 * Return the glyph index of a given character code. This function uses 4217 * the currently selected charmap to do the mapping. 4218 * 4219 * @input: 4220 * face :: 4221 * A handle to the source face object. 4222 * 4223 * charcode :: 4224 * The character code. 4225 * 4226 * @return: 4227 * The glyph index. 0~means 'undefined character code'. 4228 * 4229 * @note: 4230 * If you use FreeType to manipulate the contents of font files directly, 4231 * be aware that the glyph index returned by this function doesn't always 4232 * correspond to the internal indices used within the file. This is done 4233 * to ensure that value~0 always corresponds to the 'missing glyph'. If 4234 * the first glyph is not named '.notdef', then for Type~1 and Type~42 4235 * fonts, '.notdef' will be moved into the glyph ID~0 position, and 4236 * whatever was there will be moved to the position '.notdef' had. For 4237 * Type~1 fonts, if there is no '.notdef' glyph at all, then one will be 4238 * created at index~0 and whatever was there will be moved to the last 4239 * index -- Type~42 fonts are considered invalid under this condition. 4240 */ 4241 FT_EXPORT( FT_UInt ) 4242 FT_Get_Char_Index( FT_Face face, 4243 FT_ULong charcode ); 4244 4245 4246 /************************************************************************** 4247 * 4248 * @function: 4249 * FT_Get_First_Char 4250 * 4251 * @description: 4252 * Return the first character code in the current charmap of a given 4253 * face, together with its corresponding glyph index. 4254 * 4255 * @input: 4256 * face :: 4257 * A handle to the source face object. 4258 * 4259 * @output: 4260 * agindex :: 4261 * Glyph index of first character code. 0~if charmap is empty. 4262 * 4263 * @return: 4264 * The charmap's first character code. 4265 * 4266 * @note: 4267 * You should use this function together with @FT_Get_Next_Char to parse 4268 * all character codes available in a given charmap. The code should 4269 * look like this: 4270 * 4271 * ``` 4272 * FT_ULong charcode; 4273 * FT_UInt gindex; 4274 * 4275 * 4276 * charcode = FT_Get_First_Char( face, &gindex ); 4277 * while ( gindex != 0 ) 4278 * { 4279 * ... do something with (charcode,gindex) pair ... 4280 * 4281 * charcode = FT_Get_Next_Char( face, charcode, &gindex ); 4282 * } 4283 * ``` 4284 * 4285 * Be aware that character codes can have values up to 0xFFFFFFFF; this 4286 * might happen for non-Unicode or malformed cmaps. However, even with 4287 * regular Unicode encoding, so-called 'last resort fonts' (using SFNT 4288 * cmap format 13, see function @FT_Get_CMap_Format) normally have 4289 * entries for all Unicode characters up to 0x1FFFFF, which can cause *a 4290 * lot* of iterations. 4291 * 4292 * Note that `*agindex` is set to~0 if the charmap is empty. The result 4293 * itself can be~0 in two cases: if the charmap is empty or if the 4294 * value~0 is the first valid character code. 4295 */ 4296 FT_EXPORT( FT_ULong ) 4297 FT_Get_First_Char( FT_Face face, 4298 FT_UInt *agindex ); 4299 4300 4301 /************************************************************************** 4302 * 4303 * @function: 4304 * FT_Get_Next_Char 4305 * 4306 * @description: 4307 * Return the next character code in the current charmap of a given face 4308 * following the value `char_code`, as well as the corresponding glyph 4309 * index. 4310 * 4311 * @input: 4312 * face :: 4313 * A handle to the source face object. 4314 * 4315 * char_code :: 4316 * The starting character code. 4317 * 4318 * @output: 4319 * agindex :: 4320 * Glyph index of next character code. 0~if charmap is empty. 4321 * 4322 * @return: 4323 * The charmap's next character code. 4324 * 4325 * @note: 4326 * You should use this function with @FT_Get_First_Char to walk over all 4327 * character codes available in a given charmap. See the note for that 4328 * function for a simple code example. 4329 * 4330 * Note that `*agindex` is set to~0 when there are no more codes in the 4331 * charmap. 4332 */ 4333 FT_EXPORT( FT_ULong ) 4334 FT_Get_Next_Char( FT_Face face, 4335 FT_ULong char_code, 4336 FT_UInt *agindex ); 4337 4338 4339 /************************************************************************** 4340 * 4341 * @section: 4342 * face_creation 4343 * 4344 */ 4345 4346 /************************************************************************** 4347 * 4348 * @function: 4349 * FT_Face_Properties 4350 * 4351 * @description: 4352 * Set or override certain (library or module-wide) properties on a 4353 * face-by-face basis. Useful for finer-grained control and avoiding 4354 * locks on shared structures (threads can modify their own faces as they 4355 * see fit). 4356 * 4357 * Contrary to @FT_Property_Set, this function uses @FT_Parameter so that 4358 * you can pass multiple properties to the target face in one call. Note 4359 * that only a subset of the available properties can be controlled. 4360 * 4361 * * @FT_PARAM_TAG_STEM_DARKENING (stem darkening, corresponding to the 4362 * property `no-stem-darkening` provided by the 'autofit', 'cff', 4363 * 'type1', and 't1cid' modules; see @no-stem-darkening). 4364 * 4365 * * @FT_PARAM_TAG_LCD_FILTER_WEIGHTS (LCD filter weights, corresponding 4366 * to function @FT_Library_SetLcdFilterWeights). 4367 * 4368 * * @FT_PARAM_TAG_RANDOM_SEED (seed value for the CFF, Type~1, and CID 4369 * 'random' operator, corresponding to the `random-seed` property 4370 * provided by the 'cff', 'type1', and 't1cid' modules; see 4371 * @random-seed). 4372 * 4373 * Pass `NULL` as `data` in @FT_Parameter for a given tag to reset the 4374 * option and use the library or module default again. 4375 * 4376 * @input: 4377 * face :: 4378 * A handle to the source face object. 4379 * 4380 * num_properties :: 4381 * The number of properties that follow. 4382 * 4383 * properties :: 4384 * A handle to an @FT_Parameter array with `num_properties` elements. 4385 * 4386 * @return: 4387 * FreeType error code. 0~means success. 4388 * 4389 * @example: 4390 * Here is an example that sets three properties. You must define 4391 * `FT_CONFIG_OPTION_SUBPIXEL_RENDERING` to make the LCD filter examples 4392 * work. 4393 * 4394 * ``` 4395 * FT_Parameter property1; 4396 * FT_Bool darken_stems = 1; 4397 * 4398 * FT_Parameter property2; 4399 * FT_LcdFiveTapFilter custom_weight = 4400 * { 0x11, 0x44, 0x56, 0x44, 0x11 }; 4401 * 4402 * FT_Parameter property3; 4403 * FT_Int32 random_seed = 314159265; 4404 * 4405 * FT_Parameter properties[3] = { property1, 4406 * property2, 4407 * property3 }; 4408 * 4409 * 4410 * property1.tag = FT_PARAM_TAG_STEM_DARKENING; 4411 * property1.data = &darken_stems; 4412 * 4413 * property2.tag = FT_PARAM_TAG_LCD_FILTER_WEIGHTS; 4414 * property2.data = custom_weight; 4415 * 4416 * property3.tag = FT_PARAM_TAG_RANDOM_SEED; 4417 * property3.data = &random_seed; 4418 * 4419 * FT_Face_Properties( face, 3, properties ); 4420 * ``` 4421 * 4422 * The next example resets a single property to its default value. 4423 * 4424 * ``` 4425 * FT_Parameter property; 4426 * 4427 * 4428 * property.tag = FT_PARAM_TAG_LCD_FILTER_WEIGHTS; 4429 * property.data = NULL; 4430 * 4431 * FT_Face_Properties( face, 1, &property ); 4432 * ``` 4433 * 4434 * @since: 4435 * 2.8 4436 * 4437 */ 4438 FT_EXPORT( FT_Error ) 4439 FT_Face_Properties( FT_Face face, 4440 FT_UInt num_properties, 4441 FT_Parameter* properties ); 4442 4443 4444 /************************************************************************** 4445 * 4446 * @section: 4447 * information_retrieval 4448 * 4449 */ 4450 4451 /************************************************************************** 4452 * 4453 * @function: 4454 * FT_Get_Name_Index 4455 * 4456 * @description: 4457 * Return the glyph index of a given glyph name. This only works 4458 * for those faces where @FT_HAS_GLYPH_NAMES returns true. 4459 * 4460 * @input: 4461 * face :: 4462 * A handle to the source face object. 4463 * 4464 * glyph_name :: 4465 * The glyph name. 4466 * 4467 * @return: 4468 * The glyph index. 0~means 'undefined character code'. 4469 * 4470 * @note: 4471 * Acceptable glyph names might come from the [Adobe Glyph 4472 * List](https://github.com/adobe-type-tools/agl-aglfn). See 4473 * @FT_Get_Glyph_Name for the inverse functionality. 4474 * 4475 * This function has limited capabilities if the config macro 4476 * `FT_CONFIG_OPTION_POSTSCRIPT_NAMES` is not defined in `ftoption.h`: 4477 * It then works only for fonts that actually embed glyph names (which 4478 * many recent OpenType fonts do not). 4479 */ 4480 FT_EXPORT( FT_UInt ) 4481 FT_Get_Name_Index( FT_Face face, 4482 const FT_String* glyph_name ); 4483 4484 4485 /************************************************************************** 4486 * 4487 * @function: 4488 * FT_Get_Glyph_Name 4489 * 4490 * @description: 4491 * Retrieve the ASCII name of a given glyph in a face. This only works 4492 * for those faces where @FT_HAS_GLYPH_NAMES returns true. 4493 * 4494 * @input: 4495 * face :: 4496 * A handle to a source face object. 4497 * 4498 * glyph_index :: 4499 * The glyph index. 4500 * 4501 * buffer_max :: 4502 * The maximum number of bytes available in the buffer. 4503 * 4504 * @output: 4505 * buffer :: 4506 * A pointer to a target buffer where the name is copied to. 4507 * 4508 * @return: 4509 * FreeType error code. 0~means success. 4510 * 4511 * @note: 4512 * An error is returned if the face doesn't provide glyph names or if the 4513 * glyph index is invalid. In all cases of failure, the first byte of 4514 * `buffer` is set to~0 to indicate an empty name. 4515 * 4516 * The glyph name is truncated to fit within the buffer if it is too 4517 * long. The returned string is always zero-terminated. 4518 * 4519 * Be aware that FreeType reorders glyph indices internally so that glyph 4520 * index~0 always corresponds to the 'missing glyph' (called '.notdef'). 4521 * 4522 * This function has limited capabilities if the config macro 4523 * `FT_CONFIG_OPTION_POSTSCRIPT_NAMES` is not defined in `ftoption.h`: 4524 * It then works only for fonts that actually embed glyph names (which 4525 * many recent OpenType fonts do not). 4526 */ 4527 FT_EXPORT( FT_Error ) 4528 FT_Get_Glyph_Name( FT_Face face, 4529 FT_UInt glyph_index, 4530 FT_Pointer buffer, 4531 FT_UInt buffer_max ); 4532 4533 4534 /************************************************************************** 4535 * 4536 * @function: 4537 * FT_Get_Postscript_Name 4538 * 4539 * @description: 4540 * Retrieve the ASCII PostScript name of a given face, if available. 4541 * This only works with PostScript, TrueType, and OpenType fonts. 4542 * 4543 * @input: 4544 * face :: 4545 * A handle to the source face object. 4546 * 4547 * @return: 4548 * A pointer to the face's PostScript name. `NULL` if unavailable. 4549 * 4550 * @note: 4551 * The returned pointer is owned by the face and is destroyed with it. 4552 * 4553 * For variation fonts, this string changes if you select a different 4554 * instance, and you have to call `FT_Get_PostScript_Name` again to 4555 * retrieve it. FreeType follows Adobe TechNote #5902, 'Generating 4556 * PostScript Names for Fonts Using OpenType Font Variations'. 4557 * 4558 * https://download.macromedia.com/pub/developer/opentype/tech-notes/5902.AdobePSNameGeneration.html 4559 * 4560 * [Since 2.9] Special PostScript names for named instances are only 4561 * returned if the named instance is set with @FT_Set_Named_Instance (and 4562 * the font has corresponding entries in its 'fvar' table or is the 4563 * default named instance). If @FT_IS_VARIATION returns true, the 4564 * algorithmically derived PostScript name is provided, not looking up 4565 * special entries for named instances. 4566 */ 4567 FT_EXPORT( const char* ) 4568 FT_Get_Postscript_Name( FT_Face face ); 4569 4570 4571 /************************************************************************** 4572 * 4573 * @enum: 4574 * FT_SUBGLYPH_FLAG_XXX 4575 * 4576 * @description: 4577 * A list of constants describing subglyphs. Please refer to the 'glyf' 4578 * table description in the OpenType specification for the meaning of the 4579 * various flags (which get synthesized for non-OpenType subglyphs). 4580 * 4581 * https://docs.microsoft.com/en-us/typography/opentype/spec/glyf#composite-glyph-description 4582 * 4583 * @values: 4584 * FT_SUBGLYPH_FLAG_ARGS_ARE_WORDS :: 4585 * FT_SUBGLYPH_FLAG_ARGS_ARE_XY_VALUES :: 4586 * FT_SUBGLYPH_FLAG_ROUND_XY_TO_GRID :: 4587 * FT_SUBGLYPH_FLAG_SCALE :: 4588 * FT_SUBGLYPH_FLAG_XY_SCALE :: 4589 * FT_SUBGLYPH_FLAG_2X2 :: 4590 * FT_SUBGLYPH_FLAG_USE_MY_METRICS :: 4591 * 4592 */ 4593 #define FT_SUBGLYPH_FLAG_ARGS_ARE_WORDS 1 4594 #define FT_SUBGLYPH_FLAG_ARGS_ARE_XY_VALUES 2 4595 #define FT_SUBGLYPH_FLAG_ROUND_XY_TO_GRID 4 4596 #define FT_SUBGLYPH_FLAG_SCALE 8 4597 #define FT_SUBGLYPH_FLAG_XY_SCALE 0x40 4598 #define FT_SUBGLYPH_FLAG_2X2 0x80 4599 #define FT_SUBGLYPH_FLAG_USE_MY_METRICS 0x200 4600 4601 4602 /************************************************************************** 4603 * 4604 * @function: 4605 * FT_Get_SubGlyph_Info 4606 * 4607 * @description: 4608 * Retrieve a description of a given subglyph. Only use it if 4609 * `glyph->format` is @FT_GLYPH_FORMAT_COMPOSITE; an error is returned 4610 * otherwise. 4611 * 4612 * @input: 4613 * glyph :: 4614 * The source glyph slot. 4615 * 4616 * sub_index :: 4617 * The index of the subglyph. Must be less than 4618 * `glyph->num_subglyphs`. 4619 * 4620 * @output: 4621 * p_index :: 4622 * The glyph index of the subglyph. 4623 * 4624 * p_flags :: 4625 * The subglyph flags, see @FT_SUBGLYPH_FLAG_XXX. 4626 * 4627 * p_arg1 :: 4628 * The subglyph's first argument (if any). 4629 * 4630 * p_arg2 :: 4631 * The subglyph's second argument (if any). 4632 * 4633 * p_transform :: 4634 * The subglyph transformation (if any). 4635 * 4636 * @return: 4637 * FreeType error code. 0~means success. 4638 * 4639 * @note: 4640 * The values of `*p_arg1`, `*p_arg2`, and `*p_transform` must be 4641 * interpreted depending on the flags returned in `*p_flags`. See the 4642 * OpenType specification for details. 4643 * 4644 * https://docs.microsoft.com/en-us/typography/opentype/spec/glyf#composite-glyph-description 4645 * 4646 */ 4647 FT_EXPORT( FT_Error ) 4648 FT_Get_SubGlyph_Info( FT_GlyphSlot glyph, 4649 FT_UInt sub_index, 4650 FT_Int *p_index, 4651 FT_UInt *p_flags, 4652 FT_Int *p_arg1, 4653 FT_Int *p_arg2, 4654 FT_Matrix *p_transform ); 4655 4656 4657 /************************************************************************** 4658 * 4659 * @enum: 4660 * FT_FSTYPE_XXX 4661 * 4662 * @description: 4663 * A list of bit flags used in the `fsType` field of the OS/2 table in a 4664 * TrueType or OpenType font and the `FSType` entry in a PostScript font. 4665 * These bit flags are returned by @FT_Get_FSType_Flags; they inform 4666 * client applications of embedding and subsetting restrictions 4667 * associated with a font. 4668 * 4669 * See 4670 * https://www.adobe.com/content/dam/Adobe/en/devnet/acrobat/pdfs/FontPolicies.pdf 4671 * for more details. 4672 * 4673 * @values: 4674 * FT_FSTYPE_INSTALLABLE_EMBEDDING :: 4675 * Fonts with no fsType bit set may be embedded and permanently 4676 * installed on the remote system by an application. 4677 * 4678 * FT_FSTYPE_RESTRICTED_LICENSE_EMBEDDING :: 4679 * Fonts that have only this bit set must not be modified, embedded or 4680 * exchanged in any manner without first obtaining permission of the 4681 * font software copyright owner. 4682 * 4683 * FT_FSTYPE_PREVIEW_AND_PRINT_EMBEDDING :: 4684 * The font may be embedded and temporarily loaded on the remote 4685 * system. Documents containing Preview & Print fonts must be opened 4686 * 'read-only'; no edits can be applied to the document. 4687 * 4688 * FT_FSTYPE_EDITABLE_EMBEDDING :: 4689 * The font may be embedded but must only be installed temporarily on 4690 * other systems. In contrast to Preview & Print fonts, documents 4691 * containing editable fonts may be opened for reading, editing is 4692 * permitted, and changes may be saved. 4693 * 4694 * FT_FSTYPE_NO_SUBSETTING :: 4695 * The font may not be subsetted prior to embedding. 4696 * 4697 * FT_FSTYPE_BITMAP_EMBEDDING_ONLY :: 4698 * Only bitmaps contained in the font may be embedded; no outline data 4699 * may be embedded. If there are no bitmaps available in the font, 4700 * then the font is unembeddable. 4701 * 4702 * @note: 4703 * The flags are ORed together, thus more than a single value can be 4704 * returned. 4705 * 4706 * While the `fsType` flags can indicate that a font may be embedded, a 4707 * license with the font vendor may be separately required to use the 4708 * font in this way. 4709 */ 4710 #define FT_FSTYPE_INSTALLABLE_EMBEDDING 0x0000 4711 #define FT_FSTYPE_RESTRICTED_LICENSE_EMBEDDING 0x0002 4712 #define FT_FSTYPE_PREVIEW_AND_PRINT_EMBEDDING 0x0004 4713 #define FT_FSTYPE_EDITABLE_EMBEDDING 0x0008 4714 #define FT_FSTYPE_NO_SUBSETTING 0x0100 4715 #define FT_FSTYPE_BITMAP_EMBEDDING_ONLY 0x0200 4716 4717 4718 /************************************************************************** 4719 * 4720 * @function: 4721 * FT_Get_FSType_Flags 4722 * 4723 * @description: 4724 * Return the `fsType` flags for a font. 4725 * 4726 * @input: 4727 * face :: 4728 * A handle to the source face object. 4729 * 4730 * @return: 4731 * The `fsType` flags, see @FT_FSTYPE_XXX. 4732 * 4733 * @note: 4734 * Use this function rather than directly reading the `fs_type` field in 4735 * the @PS_FontInfoRec structure, which is only guaranteed to return the 4736 * correct results for Type~1 fonts. 4737 * 4738 * @since: 4739 * 2.3.8 4740 * 4741 */ 4742 FT_EXPORT( FT_UShort ) 4743 FT_Get_FSType_Flags( FT_Face face ); 4744 4745 4746 /************************************************************************** 4747 * 4748 * @section: 4749 * glyph_variants 4750 * 4751 * @title: 4752 * Unicode Variation Sequences 4753 * 4754 * @abstract: 4755 * The FreeType~2 interface to Unicode Variation Sequences (UVS), using 4756 * the SFNT cmap format~14. 4757 * 4758 * @description: 4759 * Many characters, especially for CJK scripts, have variant forms. They 4760 * are a sort of grey area somewhere between being totally irrelevant and 4761 * semantically distinct; for this reason, the Unicode consortium decided 4762 * to introduce Variation Sequences (VS), consisting of a Unicode base 4763 * character and a variation selector instead of further extending the 4764 * already huge number of characters. 4765 * 4766 * Unicode maintains two different sets, namely 'Standardized Variation 4767 * Sequences' and registered 'Ideographic Variation Sequences' (IVS), 4768 * collected in the 'Ideographic Variation Database' (IVD). 4769 * 4770 * https://unicode.org/Public/UCD/latest/ucd/StandardizedVariants.txt 4771 * https://unicode.org/reports/tr37/ https://unicode.org/ivd/ 4772 * 4773 * To date (January 2017), the character with the most ideographic 4774 * variations is U+9089, having 32 such IVS. 4775 * 4776 * Three Mongolian Variation Selectors have the values U+180B-U+180D; 256 4777 * generic Variation Selectors are encoded in the ranges U+FE00-U+FE0F 4778 * and U+E0100-U+E01EF. IVS currently use Variation Selectors from the 4779 * range U+E0100-U+E01EF only. 4780 * 4781 * A VS consists of the base character value followed by a single 4782 * Variation Selector. For example, to get the first variation of 4783 * U+9089, you have to write the character sequence `U+9089 U+E0100`. 4784 * 4785 * Adobe and MS decided to support both standardized and ideographic VS 4786 * with a new cmap subtable (format~14). It is an odd subtable because 4787 * it is not a mapping of input code points to glyphs, but contains lists 4788 * of all variations supported by the font. 4789 * 4790 * A variation may be either 'default' or 'non-default' for a given font. 4791 * A default variation is the one you will get for that code point if you 4792 * look it up in the standard Unicode cmap. A non-default variation is a 4793 * different glyph. 4794 * 4795 */ 4796 4797 4798 /************************************************************************** 4799 * 4800 * @function: 4801 * FT_Face_GetCharVariantIndex 4802 * 4803 * @description: 4804 * Return the glyph index of a given character code as modified by the 4805 * variation selector. 4806 * 4807 * @input: 4808 * face :: 4809 * A handle to the source face object. 4810 * 4811 * charcode :: 4812 * The character code point in Unicode. 4813 * 4814 * variantSelector :: 4815 * The Unicode code point of the variation selector. 4816 * 4817 * @return: 4818 * The glyph index. 0~means either 'undefined character code', or 4819 * 'undefined selector code', or 'no variation selector cmap subtable', 4820 * or 'current CharMap is not Unicode'. 4821 * 4822 * @note: 4823 * If you use FreeType to manipulate the contents of font files directly, 4824 * be aware that the glyph index returned by this function doesn't always 4825 * correspond to the internal indices used within the file. This is done 4826 * to ensure that value~0 always corresponds to the 'missing glyph'. 4827 * 4828 * This function is only meaningful if 4829 * a) the font has a variation selector cmap sub table, and 4830 * b) the current charmap has a Unicode encoding. 4831 * 4832 * @since: 4833 * 2.3.6 4834 * 4835 */ 4836 FT_EXPORT( FT_UInt ) 4837 FT_Face_GetCharVariantIndex( FT_Face face, 4838 FT_ULong charcode, 4839 FT_ULong variantSelector ); 4840 4841 4842 /************************************************************************** 4843 * 4844 * @function: 4845 * FT_Face_GetCharVariantIsDefault 4846 * 4847 * @description: 4848 * Check whether this variation of this Unicode character is the one to 4849 * be found in the charmap. 4850 * 4851 * @input: 4852 * face :: 4853 * A handle to the source face object. 4854 * 4855 * charcode :: 4856 * The character codepoint in Unicode. 4857 * 4858 * variantSelector :: 4859 * The Unicode codepoint of the variation selector. 4860 * 4861 * @return: 4862 * 1~if found in the standard (Unicode) cmap, 0~if found in the variation 4863 * selector cmap, or -1 if it is not a variation. 4864 * 4865 * @note: 4866 * This function is only meaningful if the font has a variation selector 4867 * cmap subtable. 4868 * 4869 * @since: 4870 * 2.3.6 4871 * 4872 */ 4873 FT_EXPORT( FT_Int ) 4874 FT_Face_GetCharVariantIsDefault( FT_Face face, 4875 FT_ULong charcode, 4876 FT_ULong variantSelector ); 4877 4878 4879 /************************************************************************** 4880 * 4881 * @function: 4882 * FT_Face_GetVariantSelectors 4883 * 4884 * @description: 4885 * Return a zero-terminated list of Unicode variation selectors found in 4886 * the font. 4887 * 4888 * @input: 4889 * face :: 4890 * A handle to the source face object. 4891 * 4892 * @return: 4893 * A pointer to an array of selector code points, or `NULL` if there is 4894 * no valid variation selector cmap subtable. 4895 * 4896 * @note: 4897 * The last item in the array is~0; the array is owned by the @FT_Face 4898 * object but can be overwritten or released on the next call to a 4899 * FreeType function. 4900 * 4901 * @since: 4902 * 2.3.6 4903 * 4904 */ 4905 FT_EXPORT( FT_UInt32* ) 4906 FT_Face_GetVariantSelectors( FT_Face face ); 4907 4908 4909 /************************************************************************** 4910 * 4911 * @function: 4912 * FT_Face_GetVariantsOfChar 4913 * 4914 * @description: 4915 * Return a zero-terminated list of Unicode variation selectors found for 4916 * the specified character code. 4917 * 4918 * @input: 4919 * face :: 4920 * A handle to the source face object. 4921 * 4922 * charcode :: 4923 * The character codepoint in Unicode. 4924 * 4925 * @return: 4926 * A pointer to an array of variation selector code points that are 4927 * active for the given character, or `NULL` if the corresponding list is 4928 * empty. 4929 * 4930 * @note: 4931 * The last item in the array is~0; the array is owned by the @FT_Face 4932 * object but can be overwritten or released on the next call to a 4933 * FreeType function. 4934 * 4935 * @since: 4936 * 2.3.6 4937 * 4938 */ 4939 FT_EXPORT( FT_UInt32* ) 4940 FT_Face_GetVariantsOfChar( FT_Face face, 4941 FT_ULong charcode ); 4942 4943 4944 /************************************************************************** 4945 * 4946 * @function: 4947 * FT_Face_GetCharsOfVariant 4948 * 4949 * @description: 4950 * Return a zero-terminated list of Unicode character codes found for the 4951 * specified variation selector. 4952 * 4953 * @input: 4954 * face :: 4955 * A handle to the source face object. 4956 * 4957 * variantSelector :: 4958 * The variation selector code point in Unicode. 4959 * 4960 * @return: 4961 * A list of all the code points that are specified by this selector 4962 * (both default and non-default codes are returned) or `NULL` if there 4963 * is no valid cmap or the variation selector is invalid. 4964 * 4965 * @note: 4966 * The last item in the array is~0; the array is owned by the @FT_Face 4967 * object but can be overwritten or released on the next call to a 4968 * FreeType function. 4969 * 4970 * @since: 4971 * 2.3.6 4972 * 4973 */ 4974 FT_EXPORT( FT_UInt32* ) 4975 FT_Face_GetCharsOfVariant( FT_Face face, 4976 FT_ULong variantSelector ); 4977 4978 4979 /************************************************************************** 4980 * 4981 * @section: 4982 * computations 4983 * 4984 * @title: 4985 * Computations 4986 * 4987 * @abstract: 4988 * Crunching fixed numbers and vectors. 4989 * 4990 * @description: 4991 * This section contains various functions used to perform computations 4992 * on 16.16 fixed-point numbers or 2D vectors. FreeType does not use 4993 * floating-point data types. 4994 * 4995 * **Attention**: Most arithmetic functions take `FT_Long` as arguments. 4996 * For historical reasons, FreeType was designed under the assumption 4997 * that `FT_Long` is a 32-bit integer; results can thus be undefined if 4998 * the arguments don't fit into 32 bits. 4999 * 5000 * @order: 5001 * FT_MulDiv 5002 * FT_MulFix 5003 * FT_DivFix 5004 * FT_RoundFix 5005 * FT_CeilFix 5006 * FT_FloorFix 5007 * FT_Vector_Transform 5008 * FT_Matrix_Multiply 5009 * FT_Matrix_Invert 5010 * 5011 */ 5012 5013 5014 /************************************************************************** 5015 * 5016 * @function: 5017 * FT_MulDiv 5018 * 5019 * @description: 5020 * Compute `(a*b)/c` with maximum accuracy, using a 64-bit intermediate 5021 * integer whenever necessary. 5022 * 5023 * This function isn't necessarily as fast as some processor-specific 5024 * operations, but is at least completely portable. 5025 * 5026 * @input: 5027 * a :: 5028 * The first multiplier. 5029 * 5030 * b :: 5031 * The second multiplier. 5032 * 5033 * c :: 5034 * The divisor. 5035 * 5036 * @return: 5037 * The result of `(a*b)/c`. This function never traps when trying to 5038 * divide by zero; it simply returns 'MaxInt' or 'MinInt' depending on 5039 * the signs of `a` and `b`. 5040 */ 5041 FT_EXPORT( FT_Long ) 5042 FT_MulDiv( FT_Long a, 5043 FT_Long b, 5044 FT_Long c ); 5045 5046 5047 /************************************************************************** 5048 * 5049 * @function: 5050 * FT_MulFix 5051 * 5052 * @description: 5053 * Compute `(a*b)/0x10000` with maximum accuracy. Its main use is to 5054 * multiply a given value by a 16.16 fixed-point factor. 5055 * 5056 * @input: 5057 * a :: 5058 * The first multiplier. 5059 * 5060 * b :: 5061 * The second multiplier. Use a 16.16 factor here whenever possible 5062 * (see note below). 5063 * 5064 * @return: 5065 * The result of `(a*b)/0x10000`. 5066 * 5067 * @note: 5068 * This function has been optimized for the case where the absolute value 5069 * of `a` is less than 2048, and `b` is a 16.16 scaling factor. As this 5070 * happens mainly when scaling from notional units to fractional pixels 5071 * in FreeType, it resulted in noticeable speed improvements between 5072 * versions 2.x and 1.x. 5073 * 5074 * As a conclusion, always try to place a 16.16 factor as the _second_ 5075 * argument of this function; this can make a great difference. 5076 */ 5077 FT_EXPORT( FT_Long ) 5078 FT_MulFix( FT_Long a, 5079 FT_Long b ); 5080 5081 5082 /************************************************************************** 5083 * 5084 * @function: 5085 * FT_DivFix 5086 * 5087 * @description: 5088 * Compute `(a*0x10000)/b` with maximum accuracy. Its main use is to 5089 * divide a given value by a 16.16 fixed-point factor. 5090 * 5091 * @input: 5092 * a :: 5093 * The numerator. 5094 * 5095 * b :: 5096 * The denominator. Use a 16.16 factor here. 5097 * 5098 * @return: 5099 * The result of `(a*0x10000)/b`. 5100 */ 5101 FT_EXPORT( FT_Long ) 5102 FT_DivFix( FT_Long a, 5103 FT_Long b ); 5104 5105 5106 /************************************************************************** 5107 * 5108 * @function: 5109 * FT_RoundFix 5110 * 5111 * @description: 5112 * Round a 16.16 fixed number. 5113 * 5114 * @input: 5115 * a :: 5116 * The number to be rounded. 5117 * 5118 * @return: 5119 * `a` rounded to the nearest 16.16 fixed integer, halfway cases away 5120 * from zero. 5121 * 5122 * @note: 5123 * The function uses wrap-around arithmetic. 5124 */ 5125 FT_EXPORT( FT_Fixed ) 5126 FT_RoundFix( FT_Fixed a ); 5127 5128 5129 /************************************************************************** 5130 * 5131 * @function: 5132 * FT_CeilFix 5133 * 5134 * @description: 5135 * Compute the smallest following integer of a 16.16 fixed number. 5136 * 5137 * @input: 5138 * a :: 5139 * The number for which the ceiling function is to be computed. 5140 * 5141 * @return: 5142 * `a` rounded towards plus infinity. 5143 * 5144 * @note: 5145 * The function uses wrap-around arithmetic. 5146 */ 5147 FT_EXPORT( FT_Fixed ) 5148 FT_CeilFix( FT_Fixed a ); 5149 5150 5151 /************************************************************************** 5152 * 5153 * @function: 5154 * FT_FloorFix 5155 * 5156 * @description: 5157 * Compute the largest previous integer of a 16.16 fixed number. 5158 * 5159 * @input: 5160 * a :: 5161 * The number for which the floor function is to be computed. 5162 * 5163 * @return: 5164 * `a` rounded towards minus infinity. 5165 */ 5166 FT_EXPORT( FT_Fixed ) 5167 FT_FloorFix( FT_Fixed a ); 5168 5169 5170 /************************************************************************** 5171 * 5172 * @function: 5173 * FT_Vector_Transform 5174 * 5175 * @description: 5176 * Transform a single vector through a 2x2 matrix. 5177 * 5178 * @inout: 5179 * vector :: 5180 * The target vector to transform. 5181 * 5182 * @input: 5183 * matrix :: 5184 * A pointer to the source 2x2 matrix. 5185 * 5186 * @note: 5187 * The result is undefined if either `vector` or `matrix` is invalid. 5188 */ 5189 FT_EXPORT( void ) 5190 FT_Vector_Transform( FT_Vector* vector, 5191 const FT_Matrix* matrix ); 5192 5193 5194 /************************************************************************** 5195 * 5196 * @section: 5197 * library_setup 5198 * 5199 */ 5200 5201 /************************************************************************** 5202 * 5203 * @enum: 5204 * FREETYPE_XXX 5205 * 5206 * @description: 5207 * These three macros identify the FreeType source code version. Use 5208 * @FT_Library_Version to access them at runtime. 5209 * 5210 * @values: 5211 * FREETYPE_MAJOR :: 5212 * The major version number. 5213 * FREETYPE_MINOR :: 5214 * The minor version number. 5215 * FREETYPE_PATCH :: 5216 * The patch level. 5217 * 5218 * @note: 5219 * The version number of FreeType if built as a dynamic link library with 5220 * the 'libtool' package is _not_ controlled by these three macros. 5221 * 5222 */ 5223 #define FREETYPE_MAJOR 2 5224 #define FREETYPE_MINOR 13 5225 #define FREETYPE_PATCH 2 5226 5227 5228 /************************************************************************** 5229 * 5230 * @function: 5231 * FT_Library_Version 5232 * 5233 * @description: 5234 * Return the version of the FreeType library being used. This is useful 5235 * when dynamically linking to the library, since one cannot use the 5236 * macros @FREETYPE_MAJOR, @FREETYPE_MINOR, and @FREETYPE_PATCH. 5237 * 5238 * @input: 5239 * library :: 5240 * A source library handle. 5241 * 5242 * @output: 5243 * amajor :: 5244 * The major version number. 5245 * 5246 * aminor :: 5247 * The minor version number. 5248 * 5249 * apatch :: 5250 * The patch version number. 5251 * 5252 * @note: 5253 * The reason why this function takes a `library` argument is because 5254 * certain programs implement library initialization in a custom way that 5255 * doesn't use @FT_Init_FreeType. 5256 * 5257 * In such cases, the library version might not be available before the 5258 * library object has been created. 5259 */ 5260 FT_EXPORT( void ) 5261 FT_Library_Version( FT_Library library, 5262 FT_Int *amajor, 5263 FT_Int *aminor, 5264 FT_Int *apatch ); 5265 5266 5267 /************************************************************************** 5268 * 5269 * @section: 5270 * other_api_data 5271 * 5272 */ 5273 5274 /************************************************************************** 5275 * 5276 * @function: 5277 * FT_Face_CheckTrueTypePatents 5278 * 5279 * @description: 5280 * Deprecated, does nothing. 5281 * 5282 * @input: 5283 * face :: 5284 * A face handle. 5285 * 5286 * @return: 5287 * Always returns false. 5288 * 5289 * @note: 5290 * Since May 2010, TrueType hinting is no longer patented. 5291 * 5292 * @since: 5293 * 2.3.5 5294 * 5295 */ 5296 FT_EXPORT( FT_Bool ) 5297 FT_Face_CheckTrueTypePatents( FT_Face face ); 5298 5299 5300 /************************************************************************** 5301 * 5302 * @function: 5303 * FT_Face_SetUnpatentedHinting 5304 * 5305 * @description: 5306 * Deprecated, does nothing. 5307 * 5308 * @input: 5309 * face :: 5310 * A face handle. 5311 * 5312 * value :: 5313 * New boolean setting. 5314 * 5315 * @return: 5316 * Always returns false. 5317 * 5318 * @note: 5319 * Since May 2010, TrueType hinting is no longer patented. 5320 * 5321 * @since: 5322 * 2.3.5 5323 * 5324 */ 5325 FT_EXPORT( FT_Bool ) 5326 FT_Face_SetUnpatentedHinting( FT_Face face, 5327 FT_Bool value ); 5328 5329 /* */ 5330 5331 5332 FT_END_HEADER 5333 5334 #endif /* FREETYPE_H_ */ 5335 5336 5337 /* END */ 5338