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