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