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