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