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