1 /***************************************************************************/ 2 /* */ 3 /* freetype.h */ 4 /* */ 5 /* FreeType high-level API and common types (specification only). */ 6 /* */ 7 /* Copyright 1996-2001, 2002 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 #pragma incomplete _off_ /* it's too hard */ 22 23 24 /*************************************************************************/ 25 /* */ 26 /* The `raster' component duplicates some of the declarations in */ 27 /* freetype.h for stand-alone use if _FREETYPE_ isn't defined. */ 28 /* */ 29 30 31 /*************************************************************************/ 32 /* */ 33 /* The FREETYPE_MAJOR and FREETYPE_MINOR macros are used to version the */ 34 /* new FreeType design, which is able to host several kinds of font */ 35 /* drivers. It starts at 2.0. */ 36 /* */ 37 #define FREETYPE_MAJOR 2 38 #define FREETYPE_MINOR 1 39 #define FREETYPE_PATCH 3 40 41 42 #include <ft2build.h> 43 #include FT_CONFIG_CONFIG_H 44 #include FT_ERRORS_H 45 #include FT_TYPES_H 46 47 48 FT_BEGIN_HEADER 49 50 51 /*************************************************************************/ 52 /*************************************************************************/ 53 /* */ 54 /* B A S I C T Y P E S */ 55 /* */ 56 /*************************************************************************/ 57 /*************************************************************************/ 58 59 60 /*************************************************************************/ 61 /* */ 62 /* <Section> */ 63 /* base_interface */ 64 /* */ 65 /* <Title> */ 66 /* Base Interface */ 67 /* */ 68 /* <Abstract> */ 69 /* The FreeType 2 base font interface. */ 70 /* */ 71 /* <Description> */ 72 /* This section describes the public high-level API of FreeType 2. */ 73 /* */ 74 /* <Order> */ 75 /* FT_Library */ 76 /* FT_Face */ 77 /* FT_Size */ 78 /* FT_GlyphSlot */ 79 /* FT_CharMap */ 80 /* FT_Encoding */ 81 /* */ 82 /* FT_FaceRec */ 83 /* */ 84 /* FT_FACE_FLAG_SCALABLE */ 85 /* FT_FACE_FLAG_FIXED_SIZES */ 86 /* FT_FACE_FLAG_FIXED_WIDTH */ 87 /* FT_FACE_FLAG_HORIZONTAL */ 88 /* FT_FACE_FLAG_VERTICAL */ 89 /* FT_FACE_FLAG_SFNT */ 90 /* FT_FACE_FLAG_KERNING */ 91 /* FT_FACE_FLAG_MULTIPLE_MASTERS */ 92 /* FT_FACE_FLAG_GLYPH_NAMES */ 93 /* FT_FACE_FLAG_EXTERNAL_STREAM */ 94 /* FT_FACE_FLAG_FAST_GLYPHS */ 95 /* */ 96 /* FT_STYLE_FLAG_BOLD */ 97 /* FT_STYLE_FLAG_ITALIC */ 98 /* */ 99 /* FT_SizeRec */ 100 /* FT_Size_Metrics */ 101 /* */ 102 /* FT_GlyphSlotRec */ 103 /* FT_Glyph_Metrics */ 104 /* FT_SubGlyph */ 105 /* */ 106 /* FT_Bitmap_Size */ 107 /* */ 108 /* FT_Init_FreeType */ 109 /* FT_Done_FreeType */ 110 /* FT_Library_Version */ 111 /* */ 112 /* FT_New_Face */ 113 /* FT_Done_Face */ 114 /* FT_New_Memory_Face */ 115 /* FT_Open_Face */ 116 /* FT_Open_Args */ 117 /* FT_Open_Flags */ 118 /* FT_Parameter */ 119 /* FT_Attach_File */ 120 /* FT_Attach_Stream */ 121 /* */ 122 /* FT_Set_Char_Size */ 123 /* FT_Set_Pixel_Sizes */ 124 /* FT_Set_Transform */ 125 /* FT_Load_Glyph */ 126 /* FT_Get_Char_Index */ 127 /* FT_Get_Name_Index */ 128 /* FT_Load_Char */ 129 /* */ 130 /* FT_LOAD_DEFAULT */ 131 /* FT_LOAD_RENDER */ 132 /* FT_LOAD_MONOCHROME */ 133 /* FT_LOAD_LINEAR_DESIGN */ 134 /* FT_LOAD_NO_SCALE */ 135 /* FT_LOAD_NO_HINTING */ 136 /* FT_LOAD_NO_BITMAP */ 137 /* FT_LOAD_CROP_BITMAP */ 138 /* */ 139 /* FT_LOAD_VERTICAL_LAYOUT */ 140 /* FT_LOAD_IGNORE_TRANSFORM */ 141 /* FT_LOAD_IGNORE_GLOBAL_ADVANCE_WIDTH */ 142 /* FT_LOAD_FORCE_AUTOHINT */ 143 /* FT_LOAD_NO_RECURSE */ 144 /* FT_LOAD_PEDANTIC */ 145 /* */ 146 /* FT_Render_Glyph */ 147 /* FT_Render_Mode */ 148 /* FT_Get_Kerning */ 149 /* FT_Kerning_Mode */ 150 /* FT_Get_Glyph_Name */ 151 /* FT_Get_Postscript_Name */ 152 /* */ 153 /* FT_CharMapRec */ 154 /* FT_Select_Charmap */ 155 /* FT_Set_Charmap */ 156 /* */ 157 /*************************************************************************/ 158 159 160 /*************************************************************************/ 161 /* */ 162 /* <Struct> */ 163 /* FT_Glyph_Metrics */ 164 /* */ 165 /* <Description> */ 166 /* A structure used to model the metrics of a single glyph. Note */ 167 /* that values are expressed in 26.6 fractional pixel format or in */ 168 /* font units, depending on context. */ 169 /* */ 170 /* <Fields> */ 171 /* width :: The glyph's width. */ 172 /* */ 173 /* height :: The glyph's height. */ 174 /* */ 175 /* horiBearingX :: Horizontal left side bearing. */ 176 /* */ 177 /* horiBearingY :: Horizontal top side bearing. */ 178 /* */ 179 /* horiAdvance :: Horizontal advance width. */ 180 /* */ 181 /* vertBearingX :: Vertical left side bearing. */ 182 /* */ 183 /* vertBearingY :: Vertical top side bearing. */ 184 /* */ 185 /* vertAdvance :: Vertical advance height. */ 186 /* */ 187 typedef struct FT_Glyph_Metrics_ 188 { 189 FT_Pos width; /* glyph width */ 190 FT_Pos height; /* glyph height */ 191 192 FT_Pos horiBearingX; /* left side bearing in horizontal layouts */ 193 FT_Pos horiBearingY; /* top side bearing in horizontal layouts */ 194 FT_Pos horiAdvance; /* advance width for horizontal layout */ 195 196 FT_Pos vertBearingX; /* left side bearing in vertical layouts */ 197 FT_Pos vertBearingY; /* top side bearing in vertical layouts */ 198 FT_Pos vertAdvance; /* advance height for vertical layout */ 199 200 } FT_Glyph_Metrics; 201 202 203 /*************************************************************************/ 204 /* */ 205 /* <Struct> */ 206 /* FT_Bitmap_Size */ 207 /* */ 208 /* <Description> */ 209 /* An extremely simple structure used to model the size of a bitmap */ 210 /* strike (i.e., a bitmap instance of the font for a given */ 211 /* resolution) in a fixed-size font face. This is used for the */ 212 /* `available_sizes' field of the FT_Face_Properties structure. */ 213 /* */ 214 /* <Fields> */ 215 /* height :: The character height in pixels. */ 216 /* */ 217 /* width :: The character width in pixels. */ 218 /* */ 219 typedef struct FT_Bitmap_Size_ 220 { 221 FT_Short height; 222 FT_Short width; 223 224 } FT_Bitmap_Size; 225 226 227 /*************************************************************************/ 228 /*************************************************************************/ 229 /* */ 230 /* O B J E C T C L A S S E S */ 231 /* */ 232 /*************************************************************************/ 233 /*************************************************************************/ 234 235 /*************************************************************************/ 236 /* */ 237 /* <Type> */ 238 /* FT_Library */ 239 /* */ 240 /* <Description> */ 241 /* A handle to a FreeType library instance. Each `library' is */ 242 /* completely independent from the others; it is the `root' of a set */ 243 /* of objects like fonts, faces, sizes, etc. */ 244 /* */ 245 /* It also embeds a memory manager (see @FT_Memory), as well as a */ 246 /* scan-line converter object (see @FT_Raster). */ 247 /* */ 248 /* <Note> */ 249 /* Library objects are normally created by @FT_Init_FreeType, and */ 250 /* destroyed with @FT_Done_FreeType. */ 251 /* */ 252 typedef struct FT_LibraryRec_ *FT_Library; 253 254 255 /*************************************************************************/ 256 /* */ 257 /* <Type> */ 258 /* FT_Module */ 259 /* */ 260 /* <Description> */ 261 /* A handle to a given FreeType module object. Each module can be a */ 262 /* font driver, a renderer, or anything else that provides services */ 263 /* to the formers. */ 264 /* */ 265 typedef struct FT_ModuleRec_* FT_Module; 266 267 268 /*************************************************************************/ 269 /* */ 270 /* <Type> */ 271 /* FT_Driver */ 272 /* */ 273 /* <Description> */ 274 /* A handle to a given FreeType font driver object. Each font driver */ 275 /* is a special module capable of creating faces from font files. */ 276 /* */ 277 typedef struct FT_DriverRec_* FT_Driver; 278 279 280 /*************************************************************************/ 281 /* */ 282 /* <Type> */ 283 /* FT_Renderer */ 284 /* */ 285 /* <Description> */ 286 /* A handle to a given FreeType renderer. A renderer is a special */ 287 /* module in charge of converting a glyph image to a bitmap, when */ 288 /* necessary. Each renderer supports a given glyph image format, and */ 289 /* one or more target surface depths. */ 290 /* */ 291 typedef struct FT_RendererRec_* FT_Renderer; 292 293 294 /*************************************************************************/ 295 /* */ 296 /* <Type> */ 297 /* FT_Face */ 298 /* */ 299 /* <Description> */ 300 /* A handle to a given typographic face object. A face object models */ 301 /* a given typeface, in a given style. */ 302 /* */ 303 /* <Note> */ 304 /* Each face object also owns a single @FT_GlyphSlot object, as well */ 305 /* as one or more @FT_Size objects. */ 306 /* */ 307 /* Use @FT_New_Face or @FT_Open_Face to create a new face object from */ 308 /* a given filepathname or a custom input stream. */ 309 /* */ 310 /* Use @FT_Done_Face to destroy it (along with its slot and sizes). */ 311 /* */ 312 /* <Also> */ 313 /* The @FT_FaceRec details the publicly accessible fields of a given */ 314 /* face object. */ 315 /* */ 316 typedef struct FT_FaceRec_* FT_Face; 317 318 319 /*************************************************************************/ 320 /* */ 321 /* <Type> */ 322 /* FT_Size */ 323 /* */ 324 /* <Description> */ 325 /* A handle to a given size object. Such an object models the data */ 326 /* that depends on the current _resolution_ and _character size_ in a */ 327 /* given @FT_Face. */ 328 /* */ 329 /* <Note> */ 330 /* Each face object owns one or more sizes. There is however a */ 331 /* single _active_ size for the face at any time that will be used by */ 332 /* functions like @FT_Load_Glyph, @FT_Get_Kerning, etc. */ 333 /* */ 334 /* You can use the @FT_Activate_Size API to change the current */ 335 /* active size of any given face. */ 336 /* */ 337 /* <Also> */ 338 /* The @FT_SizeRec structure details the publicly accessible fields */ 339 /* of a given face object. */ 340 /* */ 341 typedef struct FT_SizeRec_* FT_Size; 342 343 344 /*************************************************************************/ 345 /* */ 346 /* <Type> */ 347 /* FT_GlyphSlot */ 348 /* */ 349 /* <Description> */ 350 /* A handle to a given `glyph slot'. A slot is a container where it */ 351 /* is possible to load any one of the glyphs contained in its parent */ 352 /* face. */ 353 /* */ 354 /* In other words, each time you call @FT_Load_Glyph or */ 355 /* @FT_Load_Char, the slot's content is erased by the new glyph data, */ 356 /* i.e. the glyph's metrics, its image (bitmap or outline), and */ 357 /* other control information. */ 358 /* */ 359 /* <Also> */ 360 /* @FT_GlyphSlotRec details the publicly accessible glyph fields. */ 361 /* */ 362 typedef struct FT_GlyphSlotRec_* FT_GlyphSlot; 363 364 365 /*************************************************************************/ 366 /* */ 367 /* <Type> */ 368 /* FT_CharMap */ 369 /* */ 370 /* <Description> */ 371 /* A handle to a given character map. A charmap is used to translate */ 372 /* character codes in a given encoding into glyph indexes for its */ 373 /* parent's face. Some font formats may provide several charmaps per */ 374 /* font. */ 375 /* */ 376 /* Each face object owns zero or more charmaps, but only one of them */ 377 /* can be "active" and used by @FT_Get_Char_Index or @FT_Load_Char. */ 378 /* */ 379 /* The list of available charmaps in a face is available through the */ 380 /* "face->num_charmaps" and "face->charmaps" fields of @FT_FaceRec. */ 381 /* */ 382 /* The currently active charmap is available as "face->charmap". */ 383 /* You should call @FT_Set_Charmap to change it. */ 384 /* */ 385 /* <Note> */ 386 /* When a new face is created (either through @FT_New_Face or */ 387 /* @FT_Open_Face), the library looks for a Unicode charmap within */ 388 /* the list and automatically activates it. */ 389 /* */ 390 typedef struct FT_CharMapRec_* FT_CharMap; 391 392 393 /*************************************************************************/ 394 /* */ 395 /* <Macro> */ 396 /* FT_ENC_TAG */ 397 /* */ 398 /* <Description> */ 399 /* This macro converts four letter tags into an unsigned long. It is */ 400 /* used to define "encoding" identifiers (see @FT_Encoding). */ 401 /* */ 402 /* <Note> */ 403 /* Since many 16bit compilers don't like 32bit enumerations, you */ 404 /* should redefine this macro in case of problems to something like */ 405 /* this: */ 406 /* */ 407 /* #define FT_ENC_TAG( value, a, b, c, d ) (value) */ 408 /* */ 409 /* to get a simple enumeration without assigning special numbers. */ 410 /* */ 411 412 #ifndef FT_ENC_TAG 413 #define FT_ENC_TAG( value, a, b, c, d ) \ 414 value = ( ( (FT_UInt32)(a) << 24 ) | \ 415 ( (FT_UInt32)(b) << 16 ) | \ 416 ( (FT_UInt32)(c) << 8 ) | \ 417 (FT_UInt32)(d) ) 418 419 #endif /* FT_ENC_TAG */ 420 421 422 /*************************************************************************/ 423 /* */ 424 /* <Enum> */ 425 /* FT_Encoding */ 426 /* */ 427 /* <Description> */ 428 /* An enumeration used to specify encodings supported by charmaps. */ 429 /* Used in the @FT_Select_Charmap API function. */ 430 /* */ 431 /* <Note> */ 432 /* Because of 32-bit charcodes defined in Unicode (i.e., surrogates), */ 433 /* all character codes must be expressed as FT_Longs. */ 434 /* */ 435 /* The values of this type correspond to specific character */ 436 /* repertories (i.e. charsets), and not to text encoding methods */ 437 /* (like UTF-8, UTF-16, GB2312_EUC, etc.). */ 438 /* */ 439 /* Other encodings might be defined in the future. */ 440 /* */ 441 /* <Values> */ 442 /* FT_ENCODING_NONE :: */ 443 /* The encoding value 0 is reserved. */ 444 /* */ 445 /* FT_ENCODING_UNICODE :: */ 446 /* Corresponds to the Unicode character set. This value covers */ 447 /* all versions of the Unicode repertoire, including ASCII and */ 448 /* Latin-1. Most fonts include a Unicode charmap, but not all */ 449 /* of them. */ 450 /* */ 451 /* FT_ENCODING_MS_SYMBOL :: */ 452 /* Corresponds to the Microsoft Symbol encoding, used to encode */ 453 /* mathematical symbols in the 32..255 character code range. For */ 454 /* more information, see `http://www.ceviz.net/symbol.htm'. */ 455 /* */ 456 /* FT_ENCODING_MS_SJIS :: */ 457 /* Corresponds to Microsoft's Japanese SJIS encoding. More info */ 458 /* at `http://langsupport.japanreference.com/encoding.shtml'. */ 459 /* See note on multi-byte encodings below. */ 460 /* */ 461 /* FT_ENCODING_MS_GB2312 :: */ 462 /* Corresponds to the encoding system for Simplified Chinese, as */ 463 /* used in China. Only found in some TrueType fonts. */ 464 /* */ 465 /* FT_ENCODING_MS_BIG5 :: */ 466 /* Corresponds to the encoding system for Traditional Chinese, as */ 467 /* used in Taiwan and Hong Kong. Only found in some TrueType fonts. */ 468 /* */ 469 /* FT_ENCODING_MS_WANSUNG :: */ 470 /* Corresponds to the Korean encoding system known as Wansung. */ 471 /* This is a Microsoft encoding that is only found in some TrueType */ 472 /* fonts. For more information, see */ 473 /* `http://www.microsoft.com/typography/unicode/949.txt'. */ 474 /* */ 475 /* FT_ENCODING_MS_JOHAB :: */ 476 /* The Korean standard character set (KS C-5601-1992), which */ 477 /* corresponds to Windows code page 1361. This character set */ 478 /* includes all possible Hangeul character combinations. */ 479 /* Only found on some rare TrueType fonts. */ 480 /* */ 481 /* FT_ENCODING_ADOBE_LATIN_1 :: */ 482 /* Corresponds to a Latin-1 encoding as defined in a Type 1 */ 483 /* Postscript font. It is limited to 256 character codes. */ 484 /* */ 485 /* FT_ENCODING_ADOBE_STANDARD :: */ 486 /* Corresponds to the Adobe Standard encoding, as found in Type 1, */ 487 /* CFF, and OpenType/CFF fonts. It is limited to 256character */ 488 /* codes. */ 489 /* */ 490 /* FT_ENCODING_ADOBE_EXPERT :: */ 491 /* Corresponds to the Adobe Expert encoding, as found in Type 1, */ 492 /* CFF, and OpenType/CFF fonts. It is limited to 256 character */ 493 /* codes. */ 494 /* */ 495 /* FT_ENCODING_ADOBE_CUSTOM :: */ 496 /* Corresponds to a custom encoding, as found in Type 1, CFF, and */ 497 /* OpenType/CFF fonts. It is limited to 256 character codes. */ 498 /* */ 499 /* FT_ENCODING_APPLE_ROMAN :: */ 500 /* Corresponds to the 8-bit Apple roman encoding. Many TrueType and */ 501 /* OpenType fonts contain a charmap for this encoding, since older */ 502 /* versions of Mac OS are able to use it. */ 503 /* */ 504 /* FT_ENCODING_OLD_LATIN_2 :: */ 505 /* This value is deprecated and was never used nor reported by */ 506 /* FreeType. Don't use or test for it. */ 507 /* */ 508 /* <Note> */ 509 /* By default, FreeType automatically synthetizes a Unicode charmap */ 510 /* for Postscript fonts, using their glyph names dictionaries. */ 511 /* However, it will also report the encodings defined explicitly in */ 512 /* the font file, for the cases when they are needed, with the Adobe */ 513 /* values as well. */ 514 /* */ 515 typedef enum FT_Encoding_ 516 { 517 FT_ENC_TAG( FT_ENCODING_NONE, 0, 0, 0, 0 ), 518 519 FT_ENC_TAG( FT_ENCODING_MS_SYMBOL, 's', 'y', 'm', 'b' ), 520 FT_ENC_TAG( FT_ENCODING_UNICODE, 'u', 'n', 'i', 'c' ), 521 522 FT_ENC_TAG( FT_ENCODING_MS_SJIS, 's', 'j', 'i', 's' ), 523 FT_ENC_TAG( FT_ENCODING_MS_GB2312, 'g', 'b', ' ', ' ' ), 524 FT_ENC_TAG( FT_ENCODING_MS_BIG5, 'b', 'i', 'g', '5' ), 525 FT_ENC_TAG( FT_ENCODING_MS_WANSUNG, 'w', 'a', 'n', 's' ), 526 FT_ENC_TAG( FT_ENCODING_MS_JOHAB, 'j', 'o', 'h', 'a' ), 527 528 FT_ENC_TAG( FT_ENCODING_ADOBE_STANDARD, 'A', 'D', 'O', 'B' ), 529 FT_ENC_TAG( FT_ENCODING_ADOBE_EXPERT, 'A', 'D', 'B', 'E' ), 530 FT_ENC_TAG( FT_ENCODING_ADOBE_CUSTOM, 'A', 'D', 'B', 'C' ), 531 FT_ENC_TAG( FT_ENCODING_ADOBE_LATIN_1, 'l', 'a', 't', '1' ), 532 533 FT_ENC_TAG( FT_ENCODING_OLD_LATIN_2, 'l', 'a', 't', '2' ), 534 535 FT_ENC_TAG( FT_ENCODING_APPLE_ROMAN, 'a', 'r', 'm', 'n' ) 536 537 } FT_Encoding; 538 539 540 /*************************************************************************/ 541 /* */ 542 /* <Enum> */ 543 /* ft_encoding_xxx */ 544 /* */ 545 /* <Description> */ 546 /* These constants are deprecated; use the corresponding @FT_Encoding */ 547 /* values instead. */ 548 /* */ 549 /* <Values> */ 550 /* ft_encoding_none :: see @FT_ENCODING_NONE */ 551 /* ft_encoding_unicode :: see @FT_ENCODING_UNICODE */ 552 /* ft_encoding_latin_2 :: see @FT_ENCODING_OLD_LATIN_2 */ 553 /* ft_encoding_symbol :: see @FT_ENCODING_MS_SYMBOL */ 554 /* ft_encoding_sjis :: see @FT_ENCODING_MS_SJIS */ 555 /* ft_encoding_gb2312 :: see @FT_ENCODING_MS_GB2312 */ 556 /* ft_encoding_big5 :: see @FT_ENCODING_MS_BIG5 */ 557 /* ft_encoding_wansung :: see @FT_ENCODING_MS_WANSUNG */ 558 /* ft_encoding_johab :: see @FT_ENCODING_MS_JOHAB */ 559 /* */ 560 /* ft_encoding_adobe_standard :: see @FT_ENCODING_ADOBE_STANDARD */ 561 /* ft_encoding_adobe_expert :: see @FT_ENCODING_ADOBE_EXPERT */ 562 /* ft_encoding_adobe_custom :: see @FT_ENCODING_ADOBE_CUSTOM */ 563 /* ft_encoding_latin_1 :: see @FT_ENCODING_ADOBE_LATIN_1 */ 564 /* */ 565 /* ft_encoding_apple_roman :: see @FT_ENCODING_APPLE_ROMAN */ 566 /* */ 567 #define ft_encoding_none FT_ENCODING_NONE 568 #define ft_encoding_unicode FT_ENCODING_UNICODE 569 #define ft_encoding_symbol FT_ENCODING_MS_SYMBOL 570 #define ft_encoding_latin_1 FT_ENCODING_ADOBE_LATIN_1 571 #define ft_encoding_latin_2 FT_ENCODING_OLD_LATIN_2 572 #define ft_encoding_sjis FT_ENCODING_MS_SJIS 573 #define ft_encoding_gb2312 FT_ENCODING_MS_GB2312 574 #define ft_encoding_big5 FT_ENCODING_MS_BIG5 575 #define ft_encoding_wansung FT_ENCODING_MS_WANSUNG 576 #define ft_encoding_johab FT_ENCODING_MS_JOHAB 577 578 #define ft_encoding_adobe_standard FT_ENCODING_ADOBE_STANDARD 579 #define ft_encoding_adobe_expert FT_ENCODING_ADOBE_EXPERT 580 #define ft_encoding_adobe_custom FT_ENCODING_ADOBE_CUSTOM 581 #define ft_encoding_apple_roman FT_ENCODING_APPLE_ROMAN 582 583 584 /*************************************************************************/ 585 /* */ 586 /* <Struct> */ 587 /* FT_CharMapRec */ 588 /* */ 589 /* <Description> */ 590 /* The base charmap structure. */ 591 /* */ 592 /* <Fields> */ 593 /* face :: A handle to the parent face object. */ 594 /* */ 595 /* encoding :: An @FT_Encoding tag identifying the charmap. Use */ 596 /* this with @FT_Select_Charmap. */ 597 /* */ 598 /* platform_id :: An ID number describing the platform for the */ 599 /* following encoding ID. This comes directly from */ 600 /* the TrueType specification and should be emulated */ 601 /* for other formats. */ 602 /* */ 603 /* encoding_id :: A platform specific encoding number. This also */ 604 /* comes from the TrueType specification and should be */ 605 /* emulated similarly. */ 606 /* */ 607 typedef struct FT_CharMapRec_ 608 { 609 FT_Face face; 610 FT_Encoding encoding; 611 FT_UShort platform_id; 612 FT_UShort encoding_id; 613 614 } FT_CharMapRec; 615 616 617 /*************************************************************************/ 618 /*************************************************************************/ 619 /* */ 620 /* B A S E O B J E C T C L A S S E S */ 621 /* */ 622 /*************************************************************************/ 623 /*************************************************************************/ 624 625 626 /*************************************************************************/ 627 /* */ 628 /* <Type> */ 629 /* FT_Face_Internal */ 630 /* */ 631 /* <Description> */ 632 /* An opaque handle to an FT_Face_InternalRec structure, used to */ 633 /* model private data of a given @FT_Face object. */ 634 /* */ 635 /* This structure might change between releases of FreeType 2 and is */ 636 /* not generally available to client applications. */ 637 /* */ 638 typedef struct FT_Face_InternalRec_* FT_Face_Internal; 639 640 641 /*************************************************************************/ 642 /* */ 643 /* <Struct> */ 644 /* FT_FaceRec */ 645 /* */ 646 /* <Description> */ 647 /* FreeType root face class structure. A face object models the */ 648 /* resolution and point-size independent data found in a font file. */ 649 /* */ 650 /* <Fields> */ 651 /* num_faces :: In the case where the face is located in a */ 652 /* collection (i.e., a file which embeds */ 653 /* several faces), this is the total number of */ 654 /* faces found in the resource. 1 by default. */ 655 /* */ 656 /* face_index :: The index of the face in its font file. */ 657 /* Usually, this is 0 for all normal font */ 658 /* formats. It can be more in the case of */ 659 /* collections (which embed several fonts in a */ 660 /* single resource/file). */ 661 /* */ 662 /* face_flags :: A set of bit flags that give important */ 663 /* information about the face; see the */ 664 /* @FT_FACE_FLAG_XXX constants for details. */ 665 /* */ 666 /* style_flags :: A set of bit flags indicating the style of */ 667 /* the face (i.e., italic, bold, underline, */ 668 /* etc). See the @FT_STYLE_FLAG_XXX */ 669 /* constants. */ 670 /* */ 671 /* num_glyphs :: The total number of glyphs in the face. */ 672 /* */ 673 /* family_name :: The face's family name. This is an ASCII */ 674 /* string, usually in English, which describes */ 675 /* the typeface's family (like `Times New */ 676 /* Roman', `Bodoni', `Garamond', etc). This */ 677 /* is a least common denominator used to list */ 678 /* fonts. Some formats (TrueType & OpenType) */ 679 /* provide localized and Unicode versions of */ 680 /* this string. Applications should use the */ 681 /* format specific interface to access them. */ 682 /* */ 683 /* style_name :: The face's style name. This is an ASCII */ 684 /* string, usually in English, which describes */ 685 /* the typeface's style (like `Italic', */ 686 /* `Bold', `Condensed', etc). Not all font */ 687 /* formats provide a style name, so this field */ 688 /* is optional, and can be set to NULL. As */ 689 /* for `family_name', some formats provide */ 690 /* localized/Unicode versions of this string. */ 691 /* Applications should use the format specific */ 692 /* interface to access them. */ 693 /* */ 694 /* num_fixed_sizes :: The number of fixed sizes available in this */ 695 /* face. This should be set to 0 for scalable */ 696 /* fonts, unless its face includes a complete */ 697 /* set of glyphs (called a `strike') for the */ 698 /* specified sizes. */ 699 /* */ 700 /* available_sizes :: An array of sizes specifying the available */ 701 /* bitmap/graymap sizes that are contained in */ 702 /* in the font face. Should be set to NULL if */ 703 /* the field `num_fixed_sizes' is set to 0. */ 704 /* */ 705 /* num_charmaps :: The total number of character maps in the */ 706 /* face. */ 707 /* */ 708 /* charmaps :: A table of pointers to the face's charmaps. */ 709 /* Used to scan the list of available charmaps */ 710 /* -- this table might change after a call to */ 711 /* @FT_Attach_File or @FT_Attach_Stream (e.g. */ 712 /* if used to hook an additional encoding or */ 713 /* CMap to the face object). */ 714 /* */ 715 /* generic :: A field reserved for client uses. See the */ 716 /* @FT_Generic type description. */ 717 /* */ 718 /* bbox :: The font bounding box. Coordinates are */ 719 /* expressed in font units (see units_per_EM). */ 720 /* The box is large enough to contain any */ 721 /* glyph from the font. Thus, bbox.yMax can */ 722 /* be seen as the `maximal ascender', */ 723 /* bbox.yMin as the `minimal descender', and */ 724 /* the maximal glyph width is given by */ 725 /* `bbox.xMax-bbox.xMin' (not to be confused */ 726 /* with the maximal _advance_width_). Only */ 727 /* relevant for scalable formats. */ 728 /* */ 729 /* units_per_EM :: The number of font units per EM square for */ 730 /* this face. This is typically 2048 for */ 731 /* TrueType fonts, 1000 for Type1 fonts, and */ 732 /* should be set to the (unrealistic) value 1 */ 733 /* for fixed-sizes fonts. Only relevant for */ 734 /* scalable formats. */ 735 /* */ 736 /* ascender :: The face's ascender is the vertical */ 737 /* distance from the baseline to the topmost */ 738 /* point of any glyph in the face. This */ 739 /* field's value is positive, expressed in */ 740 /* font units. Some font designs use a value */ 741 /* different from `bbox.yMax'. Only relevant */ 742 /* for scalable formats. */ 743 /* */ 744 /* descender :: The face's descender is the vertical */ 745 /* distance from the baseline to the */ 746 /* bottommost point of any glyph in the face. */ 747 /* This field's value is *negative*, expressed */ 748 /* in font units. Some font designs use a */ 749 /* value different from `bbox.yMin'. Only */ 750 /* relevant for scalable formats. */ 751 /* */ 752 /* height :: The face's height is the vertical distance */ 753 /* from one baseline to the next when writing */ 754 /* several lines of text. Its value is always */ 755 /* positive, expressed in font units. The */ 756 /* value can be computed as */ 757 /* `ascender+descender+line_gap' where the */ 758 /* value of `line_gap' is also called */ 759 /* `external leading'. Only relevant for */ 760 /* scalable formats. */ 761 /* */ 762 /* max_advance_width :: The maximal advance width, in font units, */ 763 /* for all glyphs in this face. This can be */ 764 /* used to make word wrapping computations */ 765 /* faster. Only relevant for scalable */ 766 /* formats. */ 767 /* */ 768 /* max_advance_height :: The maximal advance height, in font units, */ 769 /* for all glyphs in this face. This is only */ 770 /* relevant for vertical layouts, and should */ 771 /* be set to the `height' for fonts that do */ 772 /* not provide vertical metrics. Only */ 773 /* relevant for scalable formats. */ 774 /* */ 775 /* underline_position :: The position, in font units, of the */ 776 /* underline line for this face. It's the */ 777 /* center of the underlining stem. Only */ 778 /* relevant for scalable formats. */ 779 /* */ 780 /* underline_thickness :: The thickness, in font units, of the */ 781 /* underline for this face. Only relevant for */ 782 /* scalable formats. */ 783 /* */ 784 /* glyph :: The face's associated glyph slot(s). This */ 785 /* object is created automatically with a new */ 786 /* face object. However, certain kinds of */ 787 /* applications (mainly tools like converters) */ 788 /* can need more than one slot to ease their */ 789 /* task. */ 790 /* */ 791 /* size :: The current active size for this face. */ 792 /* */ 793 /* charmap :: The current active charmap for this face. */ 794 /* */ 795 typedef struct FT_FaceRec_ 796 { 797 FT_Long num_faces; 798 FT_Long face_index; 799 800 FT_Long face_flags; 801 FT_Long style_flags; 802 803 FT_Long num_glyphs; 804 805 FT_String* family_name; 806 FT_String* style_name; 807 808 FT_Int num_fixed_sizes; 809 FT_Bitmap_Size* available_sizes; 810 811 FT_Int num_charmaps; 812 FT_CharMap* charmaps; 813 814 FT_Generic generic; 815 816 /*# the following are only relevant to scalable outlines */ 817 FT_BBox bbox; 818 819 FT_UShort units_per_EM; 820 FT_Short ascender; 821 FT_Short descender; 822 FT_Short height; 823 824 FT_Short max_advance_width; 825 FT_Short max_advance_height; 826 827 FT_Short underline_position; 828 FT_Short underline_thickness; 829 830 FT_GlyphSlot glyph; 831 FT_Size size; 832 FT_CharMap charmap; 833 834 /*@private begin */ 835 836 FT_Driver driver; 837 FT_Memory memory; 838 FT_Stream stream; 839 840 FT_ListRec sizes_list; 841 842 FT_Generic autohint; 843 void* extensions; 844 845 FT_Face_Internal internal; 846 847 /*@private end */ 848 849 } FT_FaceRec; 850 851 852 /*************************************************************************/ 853 /* */ 854 /* <Enum> */ 855 /* FT_FACE_FLAG_XXX */ 856 /* */ 857 /* <Description> */ 858 /* A list of bit flags used in the 'face_flags' field of the */ 859 /* @FT_FaceRec structure. They inform client applications of */ 860 /* properties of the corresponding face. */ 861 /* */ 862 /* <Values> */ 863 /* FT_FACE_FLAG_SCALABLE :: */ 864 /* Indicates that the face provides vectorial outlines. This */ 865 /* doesn't prevent embedded bitmaps, i.e., a face can have both */ 866 /* this bit and @FT_FACE_FLAG_FIXED_SIZES set */ 867 /* */ 868 /* FT_FACE_FLAG_FIXED_SIZES :: */ 869 /* Indicates that the face contains `fixed sizes', i.e., bitmap */ 870 /* strikes for some given pixel sizes. See the `num_fixed_sizes' */ 871 /* and `available_sizes' fields of @FT_FaceRec. */ 872 /* */ 873 /* FT_FACE_FLAG_FIXED_WIDTH :: */ 874 /* Indicates that the face contains fixed-width characters (like */ 875 /* Courier, Lucido, MonoType, etc.). */ 876 /* */ 877 /* FT_FACE_FLAG_SFNT :: */ 878 /* Indicates that the face uses the `sfnt' storage scheme. For */ 879 /* now, this means TrueType and OpenType. */ 880 /* */ 881 /* FT_FACE_FLAG_HORIZONTAL :: */ 882 /* Indicates that the face contains horizontal glyph metrics. This */ 883 /* should be set for all common formats. */ 884 /* */ 885 /* FT_FACE_FLAG_VERTICAL :: */ 886 /* Indicates that the face contains vertical glyph metrics. This */ 887 /* is only available in some formats, not all of them. */ 888 /* */ 889 /* FT_FACE_FLAG_KERNING :: */ 890 /* Indicates that the face contains kerning information. If set, */ 891 /* the kerning distance can be retrieved through the function */ 892 /* @FT_Get_Kerning. Note that if unset, this function will always */ 893 /* return the vector (0,0). */ 894 /* */ 895 /* FT_FACE_FLAG_FAST_GLYPHS :: */ 896 /* THIS FLAG IS DEPRECATED. DO NOT USE OR TEST IT. */ 897 /* */ 898 /* FT_FACE_FLAG_MULTIPLE_MASTERS :: */ 899 /* Indicates that the font contains multiple masters and is capable */ 900 /* of interpolating between them. See the multiple-masters */ 901 /* specific API for details. */ 902 /* */ 903 /* FT_FACE_FLAG_GLYPH_NAMES :: */ 904 /* Indicates that the font contains glyph names that can be */ 905 /* retrieved through @FT_Get_Glyph_Names. Note that some TrueType */ 906 /* fonts contain broken glyph name tables. Use the function */ 907 /* @FT_Has_PS_Glyph_Name when needed. */ 908 /* */ 909 /* FT_FACE_FLAG_EXTERNAL_STREAM :: */ 910 /* Used internally by FreeType to indicate that a face's stream was */ 911 /* provided by the client application and should not be destroyed */ 912 /* when @FT_Done_Face is called. Don't read or test this flag. */ 913 /* */ 914 #define FT_FACE_FLAG_SCALABLE ( 1L << 0 ) 915 #define FT_FACE_FLAG_FIXED_SIZES ( 1L << 1 ) 916 #define FT_FACE_FLAG_FIXED_WIDTH ( 1L << 2 ) 917 #define FT_FACE_FLAG_SFNT ( 1L << 3 ) 918 #define FT_FACE_FLAG_HORIZONTAL ( 1L << 4 ) 919 #define FT_FACE_FLAG_VERTICAL ( 1L << 5 ) 920 #define FT_FACE_FLAG_KERNING ( 1L << 6 ) 921 #define FT_FACE_FLAG_FAST_GLYPHS ( 1L << 7 ) 922 #define FT_FACE_FLAG_MULTIPLE_MASTERS ( 1L << 8 ) 923 #define FT_FACE_FLAG_GLYPH_NAMES ( 1L << 9 ) 924 #define FT_FACE_FLAG_EXTERNAL_STREAM ( 1L << 10 ) 925 926 /* */ 927 928 929 /*************************************************************************/ 930 /* */ 931 /* @macro: */ 932 /* FT_HAS_HORIZONTAL( face ) */ 933 /* */ 934 /* @description: */ 935 /* A macro that returns true whenever a face object contains */ 936 /* horizontal metrics (this is true for all font formats though). */ 937 /* */ 938 /* @also: */ 939 /* @FT_HAS_VERTICAL can be used to check for vertical metrics. */ 940 /* */ 941 #define FT_HAS_HORIZONTAL( face ) \ 942 ( face->face_flags & FT_FACE_FLAG_HORIZONTAL ) 943 944 945 /*************************************************************************/ 946 /* */ 947 /* @macro: */ 948 /* FT_HAS_VERTICAL( face ) */ 949 /* */ 950 /* @description: */ 951 /* A macro that returns true whenever a face object contains vertical */ 952 /* metrics. */ 953 /* */ 954 #define FT_HAS_VERTICAL( face ) \ 955 ( face->face_flags & FT_FACE_FLAG_VERTICAL ) 956 957 958 /*************************************************************************/ 959 /* */ 960 /* @macro: */ 961 /* FT_HAS_KERNING( face ) */ 962 /* */ 963 /* @description: */ 964 /* A macro that returns true whenever a face object contains kerning */ 965 /* data that can be accessed with @FT_Get_Kerning. */ 966 /* */ 967 #define FT_HAS_KERNING( face ) \ 968 ( face->face_flags & FT_FACE_FLAG_KERNING ) 969 970 971 /*************************************************************************/ 972 /* */ 973 /* @macro: */ 974 /* FT_IS_SCALABLE( face ) */ 975 /* */ 976 /* @description: */ 977 /* A macro that returns true whenever a face object contains a */ 978 /* scalable font face (true for TrueType, Type 1, CID, and */ 979 /* OpenType/CFF font formats. */ 980 /* */ 981 #define FT_IS_SCALABLE( face ) \ 982 ( face->face_flags & FT_FACE_FLAG_SCALABLE ) 983 984 985 /*************************************************************************/ 986 /* */ 987 /* @macro: */ 988 /* FT_IS_SFNT( face ) */ 989 /* */ 990 /* @description: */ 991 /* A macro that returns true whenever a face object contains a font */ 992 /* whose format is based on the SFNT storage scheme. This usually */ 993 /* means: TrueType fonts, OpenType fonts, as well as SFNT-based */ 994 /* embedded bitmap fonts. */ 995 /* */ 996 /* If this macro is true, all functions defined in @FT_SFNT_NAMES_H */ 997 /* and @FT_TRUETYPE_TABLES_H are available. */ 998 /* */ 999 #define FT_IS_SFNT( face ) \ 1000 ( face->face_flags & FT_FACE_FLAG_SFNT ) 1001 1002 1003 /*************************************************************************/ 1004 /* */ 1005 /* @macro: */ 1006 /* FT_IS_FIXED_WIDTH( face ) */ 1007 /* */ 1008 /* @description: */ 1009 /* A macro that returns true whenever a face object contains a font */ 1010 /* face that contains fixed-width (or "monospace", "fixed-pitch", */ 1011 /* etc.) glyphs. */ 1012 /* */ 1013 #define FT_IS_FIXED_WIDTH( face ) \ 1014 ( face->face_flags & FT_FACE_FLAG_FIXED_WIDTH ) 1015 1016 1017 /*************************************************************************/ 1018 /* */ 1019 /* @macro: */ 1020 /* FT_IS_FIXED_SIZES( face ) */ 1021 /* */ 1022 /* @description: */ 1023 /* A macro that returns true whenever a face object contains some */ 1024 /* embedded bitmaps. See the `fixed_sizes' field of the @FT_FaceRec */ 1025 /* structure. */ 1026 /* */ 1027 #define FT_HAS_FIXED_SIZES( face ) \ 1028 ( face->face_flags & FT_FACE_FLAG_FIXED_SIZES ) 1029 1030 1031 /* */ 1032 1033 1034 /*************************************************************************/ 1035 /* */ 1036 /* @macro: */ 1037 /* FT_HAS_FAST_GLYPHS( face ) */ 1038 /* */ 1039 /* @description: */ 1040 /* Deprecated; indicates that the face contains so-called "fast" */ 1041 /* glyph bitmaps. */ 1042 /* */ 1043 #define FT_HAS_FAST_GLYPHS( face ) \ 1044 ( face->face_flags & FT_FACE_FLAG_FAST_GLYPHS ) 1045 1046 1047 /*************************************************************************/ 1048 /* */ 1049 /* @macro: */ 1050 /* FT_HAS_GLYPH_NAMES( face ) */ 1051 /* */ 1052 /* @description: */ 1053 /* A macro that returns true whenever a face object contains some */ 1054 /* glyph names that can be accessed through @FT_Get_Glyph_Names. */ 1055 /* */ 1056 #define FT_HAS_GLYPH_NAMES( face ) \ 1057 ( face->face_flags & FT_FACE_FLAG_GLYPH_NAMES ) 1058 1059 1060 /*************************************************************************/ 1061 /* */ 1062 /* @macro: */ 1063 /* FT_HAS_MULTIPLE_MASTERS( face ) */ 1064 /* */ 1065 /* @description: */ 1066 /* A macro that returns true whenever a face object contains some */ 1067 /* multiple masters. The functions provided by */ 1068 /* @FT_MULTIPLE_MASTERS_H are then available to choose the exact */ 1069 /* design you want. */ 1070 /* */ 1071 #define FT_HAS_MULTIPLE_MASTERS( face ) \ 1072 ( face->face_flags & FT_FACE_FLAG_MULTIPLE_MASTERS ) 1073 1074 1075 /*************************************************************************/ 1076 /* */ 1077 /* <Constant> */ 1078 /* FT_STYLE_FLAG_XXX */ 1079 /* */ 1080 /* <Description> */ 1081 /* A list of bit-flags used to indicate the style of a given face. */ 1082 /* These are used in the `style_flags' field of @FT_FaceRec. */ 1083 /* */ 1084 /* <Values> */ 1085 /* FT_STYLE_FLAG_ITALIC :: */ 1086 /* Indicates that a given face is italicized. */ 1087 /* */ 1088 /* FT_STYLE_FLAG_BOLD :: */ 1089 /* Indicates that a given face is bold. */ 1090 /* */ 1091 #define FT_STYLE_FLAG_ITALIC ( 1 << 0 ) 1092 #define FT_STYLE_FLAG_BOLD ( 1 << 1 ) 1093 1094 1095 /*************************************************************************/ 1096 /* */ 1097 /* <Type> */ 1098 /* FT_Size_Internal */ 1099 /* */ 1100 /* <Description> */ 1101 /* An opaque handle to an FT_Size_InternalRec structure, used to */ 1102 /* model private data of a given FT_Size object. */ 1103 /* */ 1104 typedef struct FT_Size_InternalRec_* FT_Size_Internal; 1105 1106 1107 /*************************************************************************/ 1108 /* */ 1109 /* FreeType base size metrics */ 1110 /* */ 1111 /* <Struct> */ 1112 /* FT_Size_Metrics */ 1113 /* */ 1114 /* <Description> */ 1115 /* The size metrics structure returned scaled important distances for */ 1116 /* a given size object. */ 1117 /* */ 1118 /* <Fields> */ 1119 /* x_ppem :: The character width, expressed in integer pixels. */ 1120 /* This is the width of the EM square expressed in */ 1121 /* pixels, hence the term `ppem' (pixels per EM). */ 1122 /* */ 1123 /* y_ppem :: The character height, expressed in integer pixels. */ 1124 /* This is the height of the EM square expressed in */ 1125 /* pixels, hence the term `ppem' (pixels per EM). */ 1126 /* */ 1127 /* x_scale :: A simple 16.16 fixed point format coefficient used */ 1128 /* to scale horizontal distances expressed in font */ 1129 /* units to fractional (26.6) pixel coordinates. */ 1130 /* */ 1131 /* y_scale :: A simple 16.16 fixed point format coefficient used */ 1132 /* to scale vertical distances expressed in font */ 1133 /* units to fractional (26.6) pixel coordinates. */ 1134 /* */ 1135 /* ascender :: The ascender, expressed in 26.6 fixed point */ 1136 /* pixels. Always positive. */ 1137 /* */ 1138 /* descender :: The descender, expressed in 26.6 fixed point */ 1139 /* pixels. Always positive. */ 1140 /* */ 1141 /* height :: The text height, expressed in 26.6 fixed point */ 1142 /* pixels. Always positive. */ 1143 /* */ 1144 /* max_advance :: Maximum horizontal advance, expressed in 26.6 */ 1145 /* fixed point pixels. Always positive. */ 1146 /* */ 1147 /* <Note> */ 1148 /* The values of `ascender', `descender', and `height' are only the */ 1149 /* scaled versions of `face->ascender', `face->descender', and */ 1150 /* `face->height'. */ 1151 /* */ 1152 /* Unfortunately, due to glyph hinting, these values might not be */ 1153 /* exact for certain fonts, they thus must be treated as unreliable */ 1154 /* with an error margin of at least one pixel! */ 1155 /* */ 1156 /* Indeed, the only way to get the exact pixel ascender and descender */ 1157 /* is to render _all_ glyphs. As this would be a definite */ 1158 /* performance hit, it is up to client applications to perform such */ 1159 /* computations. */ 1160 /* */ 1161 typedef struct FT_Size_Metrics_ 1162 { 1163 FT_UShort x_ppem; /* horizontal pixels per EM */ 1164 FT_UShort y_ppem; /* vertical pixels per EM */ 1165 1166 FT_Fixed x_scale; /* two scales used to convert font units */ 1167 FT_Fixed y_scale; /* to 26.6 frac. pixel coordinates.. */ 1168 1169 FT_Pos ascender; /* ascender in 26.6 frac. pixels */ 1170 FT_Pos descender; /* descender in 26.6 frac. pixels */ 1171 FT_Pos height; /* text height in 26.6 frac. pixels */ 1172 FT_Pos max_advance; /* max horizontal advance, in 26.6 pixels */ 1173 1174 } FT_Size_Metrics; 1175 1176 1177 /*************************************************************************/ 1178 /* */ 1179 /* <Struct> */ 1180 /* FT_SizeRec */ 1181 /* */ 1182 /* <Description> */ 1183 /* FreeType root size class structure. A size object models the */ 1184 /* resolution and pointsize dependent data of a given face. */ 1185 /* */ 1186 /* <Fields> */ 1187 /* face :: Handle to the parent face object. */ 1188 /* */ 1189 /* generic :: A typeless pointer, which is unused by the FreeType */ 1190 /* library or any of its drivers. It can be used by */ 1191 /* client applications to link their own data to each size */ 1192 /* object. */ 1193 /* */ 1194 /* metrics :: Metrics for this size object. This field is read-only. */ 1195 /* */ 1196 typedef struct FT_SizeRec_ 1197 { 1198 FT_Face face; /* parent face object */ 1199 FT_Generic generic; /* generic pointer for client uses */ 1200 FT_Size_Metrics metrics; /* size metrics */ 1201 FT_Size_Internal internal; 1202 1203 } FT_SizeRec; 1204 1205 1206 /*************************************************************************/ 1207 /* */ 1208 /* <Struct> */ 1209 /* FT_SubGlyph */ 1210 /* */ 1211 /* <Description> */ 1212 /* The subglyph structure is an internal object used to describe */ 1213 /* subglyphs (for example, in the case of composites). */ 1214 /* */ 1215 /* <Note> */ 1216 /* The subglyph implementation is not part of the high-level API, */ 1217 /* hence the forward structure declaration. */ 1218 /* */ 1219 typedef struct FT_SubGlyphRec_* FT_SubGlyph; 1220 1221 1222 /*************************************************************************/ 1223 /* */ 1224 /* <Type> */ 1225 /* FT_Slot_Internal */ 1226 /* */ 1227 /* <Description> */ 1228 /* An opaque handle to an FT_Slot_InternalRec structure, used to */ 1229 /* model private data of a given FT_GlyphSlot object. */ 1230 /* */ 1231 typedef struct FT_Slot_InternalRec_* FT_Slot_Internal; 1232 1233 1234 /*************************************************************************/ 1235 /* */ 1236 /* <Struct> */ 1237 /* FT_GlyphSlotRec */ 1238 /* */ 1239 /* <Description> */ 1240 /* FreeType root glyph slot class structure. A glyph slot is a */ 1241 /* container where individual glyphs can be loaded, be they */ 1242 /* vectorial or bitmap/graymaps. */ 1243 /* */ 1244 /* <Fields> */ 1245 /* library :: A handle to the FreeType library instance */ 1246 /* this slot belongs to. */ 1247 /* */ 1248 /* face :: A handle to the parent face object. */ 1249 /* */ 1250 /* next :: In some cases (like some font tools), several */ 1251 /* glyph slots per face object can be a good */ 1252 /* thing. As this is rare, the glyph slots are */ 1253 /* listed through a direct, single-linked list */ 1254 /* using its `next' field. */ 1255 /* */ 1256 /* generic :: A typeless pointer which is unused by the */ 1257 /* FreeType library or any of its drivers. It */ 1258 /* can be used by client applications to link */ 1259 /* their own data to each glyph slot object. */ 1260 /* */ 1261 /* metrics :: The metrics of the last loaded glyph in the */ 1262 /* slot. The returned values depend on the last */ 1263 /* load flags (see the @FT_Load_Glyph API */ 1264 /* function) and can be expressed either in 26.6 */ 1265 /* fractional pixels or font units. */ 1266 /* */ 1267 /* Note that even when the glyph image is */ 1268 /* transformed, the metrics are not. */ 1269 /* */ 1270 /* linearHoriAdvance :: For scalable formats only, this field holds */ 1271 /* the linearly scaled horizontal advance width */ 1272 /* for the glyph (i.e. the scaled and unhinted */ 1273 /* value of the hori advance). This can be */ 1274 /* important to perform correct WYSIWYG layout. */ 1275 /* */ 1276 /* Note that this value is expressed by default */ 1277 /* in 16.16 pixels. However, when the glyph is */ 1278 /* loaded with the FT_LOAD_LINEAR_DESIGN flag, */ 1279 /* this field contains simply the value of the */ 1280 /* advance in original font units. */ 1281 /* */ 1282 /* linearVertAdvance :: For scalable formats only, this field holds */ 1283 /* the linearly scaled vertical advance height */ 1284 /* for the glyph. See linearHoriAdvance for */ 1285 /* comments. */ 1286 /* */ 1287 /* advance :: This is the transformed advance width for the */ 1288 /* glyph. */ 1289 /* */ 1290 /* format :: This field indicates the format of the image */ 1291 /* contained in the glyph slot. Typically */ 1292 /* FT_GLYPH_FORMAT_BITMAP, */ 1293 /* FT_GLYPH_FORMAT_OUTLINE, and */ 1294 /* FT_GLYPH_FORMAT_COMPOSITE, but others are */ 1295 /* possible. */ 1296 /* */ 1297 /* bitmap :: This field is used as a bitmap descriptor */ 1298 /* when the slot format is */ 1299 /* FT_GLYPH_FORMAT_BITMAP. Note that the */ 1300 /* address and content of the bitmap buffer can */ 1301 /* change between calls of @FT_Load_Glyph and a */ 1302 /* few other functions. */ 1303 /* */ 1304 /* bitmap_left :: This is the bitmap's left bearing expressed */ 1305 /* in integer pixels. Of course, this is only */ 1306 /* valid if the format is */ 1307 /* FT_GLYPH_FORMAT_BITMAP. */ 1308 /* */ 1309 /* bitmap_top :: This is the bitmap's top bearing expressed in */ 1310 /* integer pixels. Remember that this is the */ 1311 /* distance from the baseline to the top-most */ 1312 /* glyph scanline, upwards y-coordinates being */ 1313 /* *positive*. */ 1314 /* */ 1315 /* outline :: The outline descriptor for the current glyph */ 1316 /* image if its format is */ 1317 /* ft_glyph_bitmap_outline. */ 1318 /* */ 1319 /* num_subglyphs :: The number of subglyphs in a composite glyph. */ 1320 /* This format is only valid for the composite */ 1321 /* glyph format, that should normally only be */ 1322 /* loaded with the FT_LOAD_NO_RECURSE flag. */ 1323 /* */ 1324 /* subglyphs :: An array of subglyph descriptors for */ 1325 /* composite glyphs. There are `num_subglyphs' */ 1326 /* elements in there. */ 1327 /* */ 1328 /* control_data :: Certain font drivers can also return the */ 1329 /* control data for a given glyph image (e.g. */ 1330 /* TrueType bytecode, Type 1 charstrings, etc.). */ 1331 /* This field is a pointer to such data. */ 1332 /* */ 1333 /* control_len :: This is the length in bytes of the control */ 1334 /* data. */ 1335 /* */ 1336 /* other :: Really wicked formats can use this pointer to */ 1337 /* present their own glyph image to client apps. */ 1338 /* Note that the app will need to know about the */ 1339 /* image format. */ 1340 /* */ 1341 /* <Note> */ 1342 /* If @FT_Load_Glyph is called with default flags (see */ 1343 /* @FT_LOAD_DEFAULT) the glyph image is loaded in the glyph slot in */ 1344 /* its native format (e.g. a vectorial outline for TrueType and */ 1345 /* Type 1 formats). */ 1346 /* */ 1347 /* This image can later be converted into a bitmap by calling */ 1348 /* @FT_Render_Glyph. This function finds the current renderer for */ 1349 /* the native image's format then invokes it. */ 1350 /* */ 1351 /* The renderer is in charge of transforming the native image through */ 1352 /* the slot's face transformation fields, then convert it into a */ 1353 /* bitmap that is returned in `slot->bitmap'. */ 1354 /* */ 1355 /* Note that `slot->bitmap_left' and `slot->bitmap_top' are also used */ 1356 /* to specify the position of the bitmap relative to the current pen */ 1357 /* position (e.g. coordinates [0,0] on the baseline). Of course, */ 1358 /* `slot->format' is also changed to `FT_GLYPH_FORMAT_BITMAP' . */ 1359 /* */ 1360 typedef struct FT_GlyphSlotRec_ 1361 { 1362 FT_Library library; 1363 FT_Face face; 1364 FT_GlyphSlot next; 1365 FT_UInt flags; 1366 FT_Generic generic; 1367 1368 FT_Glyph_Metrics metrics; 1369 FT_Fixed linearHoriAdvance; 1370 FT_Fixed linearVertAdvance; 1371 FT_Vector advance; 1372 1373 FT_Glyph_Format format; 1374 1375 FT_Bitmap bitmap; 1376 FT_Int bitmap_left; 1377 FT_Int bitmap_top; 1378 1379 FT_Outline outline; 1380 1381 FT_UInt num_subglyphs; 1382 FT_SubGlyph subglyphs; 1383 1384 void* control_data; 1385 long control_len; 1386 1387 void* other; 1388 1389 FT_Slot_Internal internal; 1390 1391 } FT_GlyphSlotRec; 1392 1393 1394 /*************************************************************************/ 1395 /*************************************************************************/ 1396 /* */ 1397 /* F U N C T I O N S */ 1398 /* */ 1399 /*************************************************************************/ 1400 /*************************************************************************/ 1401 1402 1403 /*************************************************************************/ 1404 /* */ 1405 /* <Function> */ 1406 /* FT_Init_FreeType */ 1407 /* */ 1408 /* <Description> */ 1409 /* Initializes a new FreeType library object. The set of modules */ 1410 /* that are registered by this function is determined at build time. */ 1411 /* */ 1412 /* <Output> */ 1413 /* alibrary :: A handle to a new library object. */ 1414 /* */ 1415 /* <Return> */ 1416 /* FreeType error code. 0 means success. */ 1417 /* */ 1418 FT_EXPORT( FT_Error ) 1419 FT_Init_FreeType( FT_Library *alibrary ); 1420 1421 1422 /*************************************************************************/ 1423 /* */ 1424 /* <Function> */ 1425 /* FT_Library_Version */ 1426 /* */ 1427 /* <Description> */ 1428 /* Return the version of the FreeType library being used. This is */ 1429 /* useful when dynamically linking to the library, since one cannot */ 1430 /* use the macros FT_FREETYPE_MAJOR, FT_FREETYPE_MINOR, and */ 1431 /* FT_FREETYPE_PATCH. */ 1432 /* */ 1433 /* <Input> */ 1434 /* library :: A source library handle. */ 1435 /* */ 1436 /* <Output> */ 1437 /* amajor :: The major version number. */ 1438 /* */ 1439 /* aminor :: The minor version number. */ 1440 /* */ 1441 /* apatch :: The patch version number. */ 1442 /* */ 1443 /* <Note> */ 1444 /* The reason why this function takes a 'library' argument is because */ 1445 /* certain programs implement library initialization in a custom way */ 1446 /* that doesn't use `FT_Init_FreeType'. */ 1447 /* */ 1448 /* In such cases, the library version might not be available before */ 1449 /* the library object has been created. */ 1450 /* */ 1451 FT_EXPORT( void ) 1452 FT_Library_Version( FT_Library library, 1453 FT_Int *amajor, 1454 FT_Int *aminor, 1455 FT_Int *apatch ); 1456 1457 1458 /*************************************************************************/ 1459 /* */ 1460 /* <Function> */ 1461 /* FT_Done_FreeType */ 1462 /* */ 1463 /* <Description> */ 1464 /* Destroys a given FreeType library object and all of its childs, */ 1465 /* including resources, drivers, faces, sizes, etc. */ 1466 /* */ 1467 /* <Input> */ 1468 /* library :: A handle to the target library object. */ 1469 /* */ 1470 /* <Return> */ 1471 /* FreeType error code. 0 means success. */ 1472 /* */ 1473 FT_EXPORT( FT_Error ) 1474 FT_Done_FreeType( FT_Library library ); 1475 1476 1477 /*************************************************************************/ 1478 /* */ 1479 /* <Enum> */ 1480 /* FT_Open_Flags */ 1481 /* */ 1482 /* <Description> */ 1483 /* An enumeration used to list the bit flags used within the */ 1484 /* `flags' field of the @FT_Open_Args structure. */ 1485 /* */ 1486 /* <Fields> */ 1487 /* FT_OPEN_MEMORY :: This is a memory-based stream. */ 1488 /* */ 1489 /* FT_OPEN_STREAM :: Copy the stream from the `stream' field. */ 1490 /* */ 1491 /* FT_OPEN_PATHNAME :: Create a new input stream from a C */ 1492 /* path name. */ 1493 /* */ 1494 /* FT_OPEN_DRIVER :: Use the `driver' field. */ 1495 /* */ 1496 /* FT_OPEN_PARAMS :: Use the `num_params' & `params' field. */ 1497 /* */ 1498 /* <Note> */ 1499 /* The `FT_OPEN_MEMORY', `FT_OPEN_STREAM', and `FT_OPEN_PATHNAME' */ 1500 /* flags are mutually exclusive. */ 1501 /* */ 1502 typedef enum 1503 { 1504 FT_OPEN_MEMORY = 1, 1505 FT_OPEN_STREAM = 2, 1506 FT_OPEN_PATHNAME = 4, 1507 FT_OPEN_DRIVER = 8, 1508 FT_OPEN_PARAMS = 16 1509 1510 } FT_Open_Flags; 1511 1512 #define FT_OPEN_MEMORY FT_OPEN_MEMORY 1513 #define FT_OPEN_STREAM FT_OPEN_STREAM 1514 #define FT_OPEN_PATHNAME FT_OPEN_PATHNAME 1515 #define FT_OPEN_DRIVER FT_OPEN_DRIVER 1516 #define FT_OPEN_PARAMS FT_OPEN_PARAMS 1517 1518 1519 /*************************************************************************/ 1520 /* */ 1521 /* <Struct> */ 1522 /* FT_Parameter */ 1523 /* */ 1524 /* <Description> */ 1525 /* A simple structure used to pass more or less generic parameters */ 1526 /* to @FT_Open_Face. */ 1527 /* */ 1528 /* <Fields> */ 1529 /* tag :: A 4-byte identification tag. */ 1530 /* */ 1531 /* data :: A pointer to the parameter data. */ 1532 /* */ 1533 /* <Note> */ 1534 /* The id and function of parameters are driver-specific. */ 1535 /* */ 1536 typedef struct FT_Parameter_ 1537 { 1538 FT_ULong tag; 1539 FT_Pointer data; 1540 1541 } FT_Parameter; 1542 1543 1544 /*************************************************************************/ 1545 /* */ 1546 /* <Struct> */ 1547 /* FT_Open_Args */ 1548 /* */ 1549 /* <Description> */ 1550 /* A structure used to indicate how to open a new font file/stream. */ 1551 /* A pointer to such a structure can be used as a parameter for the */ 1552 /* functions @FT_Open_Face and @FT_Attach_Stream. */ 1553 /* */ 1554 /* <Fields> */ 1555 /* flags :: A set of bit flags indicating how to use the */ 1556 /* structure. */ 1557 /* */ 1558 /* memory_base :: The first byte of the file in memory. */ 1559 /* */ 1560 /* memory_size :: The size in bytes of the file in memory. */ 1561 /* */ 1562 /* pathname :: A pointer to an 8-bit file pathname. */ 1563 /* */ 1564 /* stream :: A handle to a source stream object. */ 1565 /* */ 1566 /* driver :: This field is exclusively used by @FT_Open_Face; */ 1567 /* it simply specifies the font driver to use to open */ 1568 /* the face. If set to 0, FreeType will try to load */ 1569 /* the face with each one of the drivers in its list. */ 1570 /* */ 1571 /* num_params :: The number of extra parameters. */ 1572 /* */ 1573 /* params :: Extra parameters passed to the font driver when */ 1574 /* opening a new face. */ 1575 /* */ 1576 /* <Note> */ 1577 /* The stream type is determined by the contents of `flags' which */ 1578 /* are tested in the following order by @FT_Open_Face: */ 1579 /* */ 1580 /* If the `FT_OPEN_MEMORY' bit is set, assume that this is a */ 1581 /* memory file of `memory_size' bytes,located at `memory_address'. */ 1582 /* */ 1583 /* Otherwise, if the `FT_OPEN_STREAM' bit is set, assume that a */ 1584 /* custom input stream `stream' is used. */ 1585 /* */ 1586 /* Otherwise, if the `FT_OPEN_PATHNAME' bit is set, assume that this */ 1587 /* is a normal file and use `pathname' to open it. */ 1588 /* */ 1589 /* If the `FT_OPEN_DRIVER' bit is set, @FT_Open_Face will only try to */ 1590 /* open the file with the driver whose handler is in `driver'. */ 1591 /* */ 1592 /* If the `FT_OPEN_PARAMS' bit is set, the parameters given by */ 1593 /* `num_params' and `params' will be used. They are ignored */ 1594 /* otherwise. */ 1595 /* */ 1596 typedef struct FT_Open_Args_ 1597 { 1598 FT_Open_Flags flags; 1599 const FT_Byte* memory_base; 1600 FT_Long memory_size; 1601 FT_String* pathname; 1602 FT_Stream stream; 1603 FT_Module driver; 1604 FT_Int num_params; 1605 FT_Parameter* params; 1606 1607 } FT_Open_Args; 1608 1609 1610 /*************************************************************************/ 1611 /* */ 1612 /* <Function> */ 1613 /* FT_New_Face */ 1614 /* */ 1615 /* <Description> */ 1616 /* Creates a new face object from a given resource and typeface index */ 1617 /* using a pathname to the font file. */ 1618 /* */ 1619 /* <InOut> */ 1620 /* library :: A handle to the library resource. */ 1621 /* */ 1622 /* <Input> */ 1623 /* pathname :: A path to the font file. */ 1624 /* */ 1625 /* face_index :: The index of the face within the resource. The */ 1626 /* first face has index 0. */ 1627 /* <Output> */ 1628 /* aface :: A handle to a new face object. */ 1629 /* */ 1630 /* <Return> */ 1631 /* FreeType error code. 0 means success. */ 1632 /* */ 1633 /* <Note> */ 1634 /* Unlike FreeType 1.x, this function automatically creates a glyph */ 1635 /* slot for the face object which can be accessed directly through */ 1636 /* `face->glyph'. */ 1637 /* */ 1638 /* @FT_New_Face can be used to determine and/or check the font format */ 1639 /* of a given font resource. If the `face_index' field is negative, */ 1640 /* the function will _not_ return any face handle in `aface'. Its */ 1641 /* return value should be 0 if the font format is recognized, or */ 1642 /* non-zero otherwise. */ 1643 /* */ 1644 /* Each new face object created with this function also owns a */ 1645 /* default @FT_Size object, accessible as `face->size'. */ 1646 /* */ 1647 FT_EXPORT( FT_Error ) 1648 FT_New_Face( FT_Library library, 1649 const char* filepathname, 1650 FT_Long face_index, 1651 FT_Face *aface ); 1652 1653 1654 /*************************************************************************/ 1655 /* */ 1656 /* <Function> */ 1657 /* FT_New_Memory_Face */ 1658 /* */ 1659 /* <Description> */ 1660 /* Creates a new face object from a given resource and typeface index */ 1661 /* using a font file already loaded into memory. */ 1662 /* */ 1663 /* <InOut> */ 1664 /* library :: A handle to the library resource. */ 1665 /* */ 1666 /* <Input> */ 1667 /* file_base :: A pointer to the beginning of the font data. */ 1668 /* */ 1669 /* file_size :: The size of the memory chunk used by the font data. */ 1670 /* */ 1671 /* face_index :: The index of the face within the resource. The */ 1672 /* first face has index 0. */ 1673 /* <Output> */ 1674 /* aface :: A handle to a new face object. */ 1675 /* */ 1676 /* <Return> */ 1677 /* FreeType error code. 0 means success. */ 1678 /* */ 1679 /* <Note> */ 1680 /* The font data bytes are used _directly_ by the @FT_Face object. */ 1681 /* This means that they are not copied, and that the client is */ 1682 /* responsible for releasing/destroying them _after_ the */ 1683 /* corresponding call to @FT_Done_Face . */ 1684 /* */ 1685 /* Unlike FreeType 1.x, this function automatically creates a glyph */ 1686 /* slot for the face object which can be accessed directly through */ 1687 /* `face->glyph'. */ 1688 /* */ 1689 /* @FT_New_Memory_Face can be used to determine and/or check the font */ 1690 /* format of a given font resource. If the `face_index' field is */ 1691 /* negative, the function will _not_ return any face handle in */ 1692 /* `aface'. Its return value should be 0 if the font format is */ 1693 /* recognized, or non-zero otherwise. */ 1694 /* */ 1695 FT_EXPORT( FT_Error ) 1696 FT_New_Memory_Face( FT_Library library, 1697 const FT_Byte* file_base, 1698 FT_Long file_size, 1699 FT_Long face_index, 1700 FT_Face *aface ); 1701 1702 1703 /*************************************************************************/ 1704 /* */ 1705 /* <Function> */ 1706 /* FT_Open_Face */ 1707 /* */ 1708 /* <Description> */ 1709 /* Opens a face object from a given resource and typeface index using */ 1710 /* an `FT_Open_Args' structure. If the face object doesn't exist, it */ 1711 /* will be created. */ 1712 /* */ 1713 /* <InOut> */ 1714 /* library :: A handle to the library resource. */ 1715 /* */ 1716 /* <Input> */ 1717 /* args :: A pointer to an `FT_Open_Args' structure which must */ 1718 /* be filled by the caller. */ 1719 /* */ 1720 /* face_index :: The index of the face within the resource. The */ 1721 /* first face has index 0. */ 1722 /* <Output> */ 1723 /* aface :: A handle to a new face object. */ 1724 /* */ 1725 /* <Return> */ 1726 /* FreeType error code. 0 means success. */ 1727 /* */ 1728 /* <Note> */ 1729 /* Unlike FreeType 1.x, this function automatically creates a glyph */ 1730 /* slot for the face object which can be accessed directly through */ 1731 /* `face->glyph'. */ 1732 /* */ 1733 /* @FT_Open_Face can be used to determine and/or check the font */ 1734 /* format of a given font resource. If the `face_index' field is */ 1735 /* negative, the function will _not_ return any face handle in */ 1736 /* `*face'. Its return value should be 0 if the font format is */ 1737 /* recognized, or non-zero otherwise. */ 1738 /* */ 1739 FT_EXPORT( FT_Error ) 1740 FT_Open_Face( FT_Library library, 1741 const FT_Open_Args* args, 1742 FT_Long face_index, 1743 FT_Face *aface ); 1744 1745 1746 /*************************************************************************/ 1747 /* */ 1748 /* <Function> */ 1749 /* FT_Attach_File */ 1750 /* */ 1751 /* <Description> */ 1752 /* `Attaches' a given font file to an existing face. This is usually */ 1753 /* to read additional information for a single face object. For */ 1754 /* example, it is used to read the AFM files that come with Type 1 */ 1755 /* fonts in order to add kerning data and other metrics. */ 1756 /* */ 1757 /* <InOut> */ 1758 /* face :: The target face object. */ 1759 /* */ 1760 /* <Input> */ 1761 /* filepathname :: An 8-bit pathname naming the `metrics' file. */ 1762 /* */ 1763 /* <Return> */ 1764 /* FreeType error code. 0 means success. */ 1765 /* */ 1766 /* <Note> */ 1767 /* If your font file is in memory, or if you want to provide your */ 1768 /* own input stream object, use @FT_Attach_Stream. */ 1769 /* */ 1770 /* The meaning of the `attach' action (i.e., what really happens when */ 1771 /* the new file is read) is not fixed by FreeType itself. It really */ 1772 /* depends on the font format (and thus the font driver). */ 1773 /* */ 1774 /* Client applications are expected to know what they are doing */ 1775 /* when invoking this function. Most drivers simply do not implement */ 1776 /* file attachments. */ 1777 /* */ 1778 FT_EXPORT( FT_Error ) 1779 FT_Attach_File( FT_Face face, 1780 const char* filepathname ); 1781 1782 1783 /*************************************************************************/ 1784 /* */ 1785 /* <Function> */ 1786 /* FT_Attach_Stream */ 1787 /* */ 1788 /* <Description> */ 1789 /* This function is similar to @FT_Attach_File with the exception */ 1790 /* that it reads the attachment from an arbitrary stream. */ 1791 /* */ 1792 /* <InOut> */ 1793 /* face :: The target face object. */ 1794 /* */ 1795 /* <Input> */ 1796 /* parameters :: A pointer to an FT_Open_Args structure used to */ 1797 /* describe the input stream to FreeType. */ 1798 /* <Return> */ 1799 /* FreeType error code. 0 means success. */ 1800 /* */ 1801 /* <Note> */ 1802 /* The meaning of the `attach' (i.e. what really happens when the */ 1803 /* new file is read) is not fixed by FreeType itself. It really */ 1804 /* depends on the font format (and thus the font driver). */ 1805 /* */ 1806 /* Client applications are expected to know what they are doing */ 1807 /* when invoking this function. Most drivers simply do not implement */ 1808 /* file attachments. */ 1809 /* */ 1810 FT_EXPORT( FT_Error ) 1811 FT_Attach_Stream( FT_Face face, 1812 FT_Open_Args* parameters ); 1813 1814 1815 /*************************************************************************/ 1816 /* */ 1817 /* <Function> */ 1818 /* FT_Done_Face */ 1819 /* */ 1820 /* <Description> */ 1821 /* Discards a given face object, as well as all of its child slots */ 1822 /* and sizes. */ 1823 /* */ 1824 /* <Input> */ 1825 /* face :: A handle to a target face object. */ 1826 /* */ 1827 /* <Return> */ 1828 /* FreeType error code. 0 means success. */ 1829 /* */ 1830 FT_EXPORT( FT_Error ) 1831 FT_Done_Face( FT_Face face ); 1832 1833 1834 /*************************************************************************/ 1835 /* */ 1836 /* <Function> */ 1837 /* FT_Set_Char_Size */ 1838 /* */ 1839 /* <Description> */ 1840 /* Sets the character dimensions of a given face object. The */ 1841 /* `char_width' and `char_height' values are used for the width and */ 1842 /* height, respectively, expressed in 26.6 fractional points. */ 1843 /* */ 1844 /* If the horizontal or vertical resolution values are zero, a */ 1845 /* default value of 72dpi is used. Similarly, if one of the */ 1846 /* character dimensions is zero, its value is set equal to the other. */ 1847 /* */ 1848 /* <InOut> */ 1849 /* size :: A handle to a target size object. */ 1850 /* */ 1851 /* <Input> */ 1852 /* char_width :: The character width, in 26.6 fractional points. */ 1853 /* */ 1854 /* char_height :: The character height, in 26.6 fractional */ 1855 /* points. */ 1856 /* */ 1857 /* horz_resolution :: The horizontal resolution. */ 1858 /* */ 1859 /* vert_resolution :: The vertical resolution. */ 1860 /* */ 1861 /* <Return> */ 1862 /* FreeType error code. 0 means success. */ 1863 /* */ 1864 /* <Note> */ 1865 /* When dealing with fixed-size faces (i.e., non-scalable formats), */ 1866 /* use the function @FT_Set_Pixel_Sizes. */ 1867 /* */ 1868 FT_EXPORT( FT_Error ) 1869 FT_Set_Char_Size( FT_Face face, 1870 FT_F26Dot6 char_width, 1871 FT_F26Dot6 char_height, 1872 FT_UInt horz_resolution, 1873 FT_UInt vert_resolution ); 1874 1875 1876 /*************************************************************************/ 1877 /* */ 1878 /* <Function> */ 1879 /* FT_Set_Pixel_Sizes */ 1880 /* */ 1881 /* <Description> */ 1882 /* Sets the character dimensions of a given face object. The width */ 1883 /* and height are expressed in integer pixels. */ 1884 /* */ 1885 /* If one of the character dimensions is zero, its value is set equal */ 1886 /* to the other. */ 1887 /* */ 1888 /* <InOut> */ 1889 /* face :: A handle to the target face object. */ 1890 /* */ 1891 /* <Input> */ 1892 /* pixel_width :: The character width, in integer pixels. */ 1893 /* */ 1894 /* pixel_height :: The character height, in integer pixels. */ 1895 /* */ 1896 /* <Return> */ 1897 /* FreeType error code. 0 means success. */ 1898 /* */ 1899 /* */ 1900 /* <Note> */ 1901 /* The values of `pixel_width' and `pixel_height' correspond to the */ 1902 /* pixel values of the _typographic_ character size, which are NOT */ 1903 /* necessarily the same as the dimensions of the glyph `bitmap */ 1904 /* cells'. */ 1905 /* */ 1906 /* The `character size' is really the size of an abstract square */ 1907 /* called the `EM', used to design the font. However, depending */ 1908 /* on the font design, glyphs will be smaller or greater than the */ 1909 /* EM. */ 1910 /* */ 1911 /* This means that setting the pixel size to, say, 8x8 doesn't */ 1912 /* guarantee in any way that you will get glyph bitmaps that all fit */ 1913 /* within an 8x8 cell (sometimes even far from it). */ 1914 /* */ 1915 FT_EXPORT( FT_Error ) 1916 FT_Set_Pixel_Sizes( FT_Face face, 1917 FT_UInt pixel_width, 1918 FT_UInt pixel_height ); 1919 1920 1921 /*************************************************************************/ 1922 /* */ 1923 /* <Function> */ 1924 /* FT_Load_Glyph */ 1925 /* */ 1926 /* <Description> */ 1927 /* A function used to load a single glyph within a given glyph slot, */ 1928 /* for a given size. */ 1929 /* */ 1930 /* <InOut> */ 1931 /* face :: A handle to the target face object where the glyph */ 1932 /* will be loaded. */ 1933 /* */ 1934 /* <Input> */ 1935 /* glyph_index :: The index of the glyph in the font file. */ 1936 /* */ 1937 /* load_flags :: A flag indicating what to load for this glyph. The */ 1938 /* @FT_LOAD_XXX constants can be used to control the */ 1939 /* glyph loading process (e.g., whether the outline */ 1940 /* should be scaled, whether to load bitmaps or not, */ 1941 /* whether to hint the outline, etc). */ 1942 /* */ 1943 /* <Return> */ 1944 /* FreeType error code. 0 means success. */ 1945 /* */ 1946 /* <Note> */ 1947 /* If the glyph image is not a bitmap, and if the bit flag */ 1948 /* FT_LOAD_IGNORE_TRANSFORM is unset, the glyph image will be */ 1949 /* transformed with the information passed to a previous call to */ 1950 /* @FT_Set_Transform. */ 1951 /* */ 1952 /* Note that this also transforms the `face.glyph.advance' field, but */ 1953 /* *not* the values in `face.glyph.metrics'. */ 1954 /* */ 1955 FT_EXPORT( FT_Error ) 1956 FT_Load_Glyph( FT_Face face, 1957 FT_UInt glyph_index, 1958 FT_Int32 load_flags ); 1959 1960 1961 /*************************************************************************/ 1962 /* */ 1963 /* <Function> */ 1964 /* FT_Load_Char */ 1965 /* */ 1966 /* <Description> */ 1967 /* A function used to load a single glyph within a given glyph slot, */ 1968 /* for a given size, according to its character code. */ 1969 /* */ 1970 /* <InOut> */ 1971 /* face :: A handle to a target face object where the glyph */ 1972 /* will be loaded. */ 1973 /* */ 1974 /* <Input> */ 1975 /* char_code :: The glyph's character code, according to the */ 1976 /* current charmap used in the face. */ 1977 /* */ 1978 /* load_flags :: A flag indicating what to load for this glyph. The */ 1979 /* @FT_LOAD_XXX constants can be used to control the */ 1980 /* glyph loading process (e.g., whether the outline */ 1981 /* should be scaled, whether to load bitmaps or not, */ 1982 /* whether to hint the outline, etc). */ 1983 /* */ 1984 /* <Return> */ 1985 /* FreeType error code. 0 means success. */ 1986 /* */ 1987 /* <Note> */ 1988 /* If the face has no current charmap, or if the character code */ 1989 /* is not defined in the charmap, this function will return an */ 1990 /* error. */ 1991 /* */ 1992 /* If the glyph image is not a bitmap, and if the bit flag */ 1993 /* FT_LOAD_IGNORE_TRANSFORM is unset, the glyph image will be */ 1994 /* transformed with the information passed to a previous call to */ 1995 /* @FT_Set_Transform. */ 1996 /* */ 1997 /* Note that this also transforms the `face.glyph.advance' field, but */ 1998 /* *not* the values in `face.glyph.metrics'. */ 1999 /* */ 2000 FT_EXPORT( FT_Error ) 2001 FT_Load_Char( FT_Face face, 2002 FT_ULong char_code, 2003 FT_Int32 load_flags ); 2004 2005 2006 /**************************************************************************** 2007 * 2008 * @enum: 2009 * FT_LOAD_XXX 2010 * 2011 * @description: 2012 * A list of bit-field constants, used with @FT_Load_Glyph to indicate 2013 * what kind of operations to perform during glyph loading. 2014 * 2015 * @values: 2016 * FT_LOAD_DEFAULT :: 2017 * Corresponding to 0, this value is used a default glyph load. In this 2018 * case, the following will happen: 2019 * 2020 * 1. FreeType looks for a bitmap for the glyph corresponding to the 2021 * face's current size. If one is found, the function returns. The 2022 * bitmap data can be accessed from the glyph slot (see note below). 2023 * 2024 * 2. If no embedded bitmap is searched or found, FreeType looks for a 2025 * scalable outline. If one is found, it is loaded from the font 2026 * file, scaled to device pixels, then "hinted" to the pixel grid in 2027 * order to optimize it. The outline data can be accessed from the 2028 * glyph slot (see note below). 2029 * 2030 * Note that by default, the glyph loader doesn't render outlines into 2031 * bitmaps. The following flags are used to modify this default 2032 * behaviour to more specific and useful cases. 2033 * 2034 * FT_LOAD_NO_SCALE :: 2035 * Don't scale the vector outline being loaded to 26.6 fractional 2036 * pixels, but kept in font units. Note that this also disables 2037 * hinting and the loading of embedded bitmaps. You should only use it 2038 * when you want to retrieve the original glyph outlines in font units. 2039 * 2040 * FT_LOAD_NO_HINTING :: 2041 * Don't hint glyph outlines after their scaling to device pixels. 2042 * This generally generates "blurrier" glyphs in anti-aliased modes. 2043 * 2044 * This flag is ignored if @FT_LOAD_NO_SCALE is set. 2045 * 2046 * FT_LOAD_RENDER :: 2047 * Render the glyph outline immediately into a bitmap before the glyph 2048 * loader returns. By default, the glyph is rendered for the 2049 * @FT_RENDER_MODE_NORMAL mode, which corresponds to 8-bit anti-aliased 2050 * bitmaps using 256 opacity levels. You can use either 2051 * @FT_LOAD_TARGET_MONO or @FT_LOAD_MONOCHROME to render 1-bit 2052 * monochrome bitmaps. 2053 * 2054 * This flag is ignored if @FT_LOAD_NO_SCALE is set. 2055 * 2056 * FT_LOAD_NO_BITMAP :: 2057 * Don't look for bitmaps when loading the glyph. Only scalable 2058 * outlines will be loaded when available, and scaled, hinted, or 2059 * rendered depending on other bit flags. 2060 * 2061 * This does not prevent you from rendering outlines to bitmaps 2062 * with @FT_LOAD_RENDER, however. 2063 * 2064 * FT_LOAD_VERTICAL_LAYOUT :: 2065 * Prepare the glyph image for vertical text layout. This basically 2066 * means that `face.glyph.advance' will correspond to the vertical 2067 * advance height (instead of the default horizontal advance width), 2068 * and that the glyph image will be translated to match the vertical 2069 * bearings positions. 2070 * 2071 * FT_LOAD_FORCE_AUTOHINT :: 2072 * Force the use of the FreeType auto-hinter when a glyph outline is 2073 * loaded. You shouldn't need this in a typical application, since it 2074 * is mostly used to experiment with its algorithm. 2075 * 2076 * FT_LOAD_CROP_BITMAP :: 2077 * Indicates that the glyph loader should try to crop the bitmap (i.e., 2078 * remove all space around its black bits) when loading it. This is 2079 * only useful when loading embedded bitmaps in certain fonts, since 2080 * bitmaps rendered with @FT_LOAD_RENDER are always cropped by default. 2081 * 2082 * FT_LOAD_PEDANTIC :: 2083 * Indicates that the glyph loader should perform pedantic 2084 * verifications during glyph loading, rejecting invalid fonts. This 2085 * is mostly used to detect broken glyphs in fonts. By default, 2086 * FreeType tries to handle broken fonts also. 2087 * 2088 * FT_LOAD_IGNORE_GLOBAL_ADVANCE_WIDTH :: 2089 * Indicates that the glyph loader should ignore the global advance 2090 * width defined in the font. As far as we know, this is only used by 2091 * the X-TrueType font server, in order to deal correctly with the 2092 * incorrect metrics contained in DynaLab's TrueType CJK fonts. 2093 * 2094 * FT_LOAD_NO_RECURSE :: 2095 * This flag is only used internally. It merely indicates that the 2096 * glyph loader should not load composite glyphs recursively. Instead, 2097 * it should set the `num_subglyph' and `subglyphs' values of the glyph 2098 * slot accordingly, and set "glyph->format" to 2099 * @FT_GLYPH_FORMAT_COMPOSITE. 2100 * 2101 * The description of sub-glyphs is not available to client 2102 * applications for now. 2103 * 2104 * FT_LOAD_IGNORE_TRANSFORM :: 2105 * Indicates that the glyph loader should not try to transform the 2106 * loaded glyph image. This doesn't prevent scaling, hinting, or 2107 * rendering. 2108 * 2109 * FT_LOAD_MONOCHROME :: 2110 * This flag is used with @FT_LOAD_RENDER to indicate that you want 2111 * to render a 1-bit monochrome glyph bitmap from a vectorial outline. 2112 * 2113 * Note that this has no effect on the hinting algorithm used by the 2114 * glyph loader. You should better use @FT_LOAD_TARGET_MONO if you 2115 * want to render monochrome-optimized glyph images instead. 2116 * 2117 * FT_LOAD_LINEAR_DESIGN :: 2118 * Return the linearly scaled metrics expressed in original font units 2119 * instead of the default 16.16 pixel values. 2120 * 2121 * FT_LOAD_NO_AUTOHINT :: 2122 * Indicates that the auto-hinter should never be used to hint glyph 2123 * outlines. This doesn't prevent native format-specific hinters from 2124 * being used. This can be important for certain fonts where unhinted 2125 * output is better than auto-hinted one. 2126 */ 2127 #define FT_LOAD_NO_SCALE 0x1 2128 #define FT_LOAD_NO_HINTING 0x2 2129 #define FT_LOAD_RENDER 0x4 2130 #define FT_LOAD_NO_BITMAP 0x8 2131 #define FT_LOAD_VERTICAL_LAYOUT 0x10 2132 #define FT_LOAD_FORCE_AUTOHINT 0x20 2133 #define FT_LOAD_CROP_BITMAP 0x40 2134 #define FT_LOAD_PEDANTIC 0x80 2135 #define FT_LOAD_IGNORE_GLOBAL_ADVANCE_WIDTH 0x200 2136 #define FT_LOAD_NO_RECURSE 0x400 2137 #define FT_LOAD_IGNORE_TRANSFORM 0x800 2138 #define FT_LOAD_MONOCHROME 0x1000 2139 #define FT_LOAD_LINEAR_DESIGN 0x2000 2140 2141 /* temporary hack! */ 2142 #define FT_LOAD_SBITS_ONLY 0x4000 2143 #define FT_LOAD_NO_AUTOHINT 0x8000U 2144 2145 /* */ 2146 2147 #define FT_LOAD_TARGET_( x ) ( (FT_Int32)( (x) & 15 ) << 16 ) 2148 #define FT_LOAD_TARGET_MODE( x ) ( (FT_Render_Mode)( ( (x) >> 16 ) & 15 ) ) 2149 2150 #define FT_LOAD_TARGET_NORMAL FT_LOAD_TARGET_( FT_RENDER_MODE_NORMAL ) 2151 #define FT_LOAD_TARGET_LIGHT FT_LOAD_TARGET_( FT_RENDER_MODE_LIGHT ) 2152 #define FT_LOAD_TARGET_MONO FT_LOAD_TARGET_( FT_RENDER_MODE_MONO ) 2153 #define FT_LOAD_TARGET_LCD FT_LOAD_TARGET_( FT_RENDER_MODE_LCD ) 2154 #define FT_LOAD_TARGET_LCD_V FT_LOAD_TARGET_( FT_RENDER_MODE_LCD_V ) 2155 2156 #define FT_LOAD_DEFAULT 0x0 2157 2158 2159 /*************************************************************************/ 2160 /* */ 2161 /* <Function> */ 2162 /* FT_Set_Transform */ 2163 /* */ 2164 /* <Description> */ 2165 /* A function used to set the transformation that is applied to glyph */ 2166 /* images just before they are converted to bitmaps in a glyph slot */ 2167 /* when @FT_Render_Glyph is called. */ 2168 /* */ 2169 /* <InOut> */ 2170 /* face :: A handle to the source face object. */ 2171 /* */ 2172 /* <Input> */ 2173 /* matrix :: A pointer to the transformation's 2x2 matrix. Use 0 for */ 2174 /* the identity matrix. */ 2175 /* delta :: A pointer to the translation vector. Use 0 for the null */ 2176 /* vector. */ 2177 /* */ 2178 /* <Note> */ 2179 /* The transformation is only applied to scalable image formats after */ 2180 /* the glyph has been loaded. It means that hinting is unaltered by */ 2181 /* the transformation and is performed on the character size given in */ 2182 /* the last call to @FT_Set_Char_Sizes or @FT_Set_Pixel_Sizes. */ 2183 /* */ 2184 FT_EXPORT( void ) 2185 FT_Set_Transform( FT_Face face, 2186 FT_Matrix* matrix, 2187 FT_Vector* delta ); 2188 2189 2190 /*************************************************************************/ 2191 /* */ 2192 /* <Enum> */ 2193 /* FT_Render_Mode */ 2194 /* */ 2195 /* <Description> */ 2196 /* An enumeration type that lists the render modes supported by */ 2197 /* FreeType 2. Each mode corresponds to a specific type of scanline */ 2198 /* conversion performed on the outline, as well as specific */ 2199 /* hinting optimizations. */ 2200 /* */ 2201 /* <Values> */ 2202 /* FT_RENDER_MODE_NORMAL :: */ 2203 /* This is the default render mode; it corresponds to 8-bit */ 2204 /* anti-aliased bitmaps, using 256 levels of opacity. */ 2205 /* */ 2206 /* FT_RENDER_MODE_LIGHT :: */ 2207 /* This is similar to @FT_RENDER_MODE_NORMAL, except that this */ 2208 /* changes the hinting to prevent stem width quantization. This */ 2209 /* results in glyph shapes that are more similar to the original, */ 2210 /* while being a bit more fuzzy ("better shapes", instead of */ 2211 /* "better contrast" if you want :-) THIS IS STILL EXPERIMENTAL, */ 2212 /* FOR NOW, THIS WILL PRODUCE RESULTS SIMILAR TO NORMAL MODE !! */ 2213 /* */ 2214 /* FT_RENDER_MODE_MONO :: */ 2215 /* This mode corresponds to 1-bit bitmaps. */ 2216 /* */ 2217 /* FT_RENDER_MODE_LCD :: */ 2218 /* This mode corresponds to horizontal RGB/BGR sub-pixel displays, */ 2219 /* like LCD-screens. It produces 8-bit bitmaps that are 3 times */ 2220 /* the width of the original glyph outline in pixels, and which use */ 2221 /* the @FT_PIXEL_MODE_LCD mode. THIS IS STILL EXPERIMENTAL, DO NOT */ 2222 /* USE FOR NOW !! */ 2223 /* */ 2224 /* FT_RENDER_MODE_LCD_V :: */ 2225 /* This mode corresponds to vertical RGB/BGR sub-pixel displays */ 2226 /* (like PDA screens, rotated LCD displays, etc.). It produces */ 2227 /* 8-bit bitmaps that are 3 times the height of the original */ 2228 /* glyph outline in pixels and use the @FT_PIXEL_MODE_LCD_V mode. */ 2229 /* */ 2230 /* <Note> */ 2231 /* The LCD-optimized glyph bitmaps produced by FT_Render_Glyph are */ 2232 /* _not filtered_ to reduce color-fringes. It is up to the caller to */ 2233 /* perform this pass. THIS IS STILL EXPERIMENTAL, DO NOT USE FOR NOW */ 2234 /* !! */ 2235 /* */ 2236 typedef enum FT_Render_Mode_ 2237 { 2238 FT_RENDER_MODE_NORMAL = 0, 2239 FT_RENDER_MODE_LIGHT, 2240 FT_RENDER_MODE_MONO, 2241 FT_RENDER_MODE_LCD, 2242 FT_RENDER_MODE_LCD_V, 2243 2244 FT_RENDER_MODE_MAX 2245 2246 } FT_Render_Mode; 2247 2248 2249 /*************************************************************************/ 2250 /* */ 2251 /* <Enum> */ 2252 /* ft_render_mode_xxx */ 2253 /* */ 2254 /* <Description> */ 2255 /* These constats are deprecated. Use the corresponding */ 2256 /* @FT_Render_Mode values instead. */ 2257 /* */ 2258 /* <Values> */ 2259 /* ft_render_mode_normal :: see @FT_RENDER_MODE_NORMAL */ 2260 /* ft_render_mode_mono :: see @FT_RENDER_MODE_MONO */ 2261 /* */ 2262 #define ft_render_mode_normal FT_RENDER_MODE_NORMAL 2263 #define ft_render_mode_mono FT_RENDER_MODE_MONO 2264 2265 2266 /*************************************************************************/ 2267 /* */ 2268 /* <Function> */ 2269 /* FT_Render_Glyph */ 2270 /* */ 2271 /* <Description> */ 2272 /* Converts a given glyph image to a bitmap. It does so by */ 2273 /* inspecting the glyph image format, find the relevant renderer, and */ 2274 /* invoke it. */ 2275 /* */ 2276 /* <InOut> */ 2277 /* slot :: A handle to the glyph slot containing the image to */ 2278 /* convert. */ 2279 /* */ 2280 /* <Input> */ 2281 /* render_mode :: This is the render mode used to render the glyph */ 2282 /* image into a bitmap. See FT_Render_Mode for a list */ 2283 /* of possible values. */ 2284 /* */ 2285 /* <Return> */ 2286 /* FreeType error code. 0 means success. */ 2287 /* */ 2288 FT_EXPORT( FT_Error ) 2289 FT_Render_Glyph( FT_GlyphSlot slot, 2290 FT_Render_Mode render_mode ); 2291 2292 2293 /*************************************************************************/ 2294 /* */ 2295 /* <Enum> */ 2296 /* FT_Kerning_Mode */ 2297 /* */ 2298 /* <Description> */ 2299 /* An enumeration used to specify which kerning values to return in */ 2300 /* @FT_Get_Kerning. */ 2301 /* */ 2302 /* <Values> */ 2303 /* FT_KERNING_DEFAULT :: Return scaled and grid-fitted kerning */ 2304 /* distances (value is 0). */ 2305 /* */ 2306 /* FT_KERNING_UNFITTED :: Return scaled but un-grid-fitted kerning */ 2307 /* distances. */ 2308 /* */ 2309 /* FT_KERNING_UNSCALED :: Return the kerning vector in original font */ 2310 /* units. */ 2311 /* */ 2312 typedef enum FT_Kerning_Mode_ 2313 { 2314 FT_KERNING_DEFAULT = 0, 2315 FT_KERNING_UNFITTED, 2316 FT_KERNING_UNSCALED 2317 2318 } FT_Kerning_Mode; 2319 2320 2321 /*************************************************************************/ 2322 /* */ 2323 /* <Const> */ 2324 /* ft_kerning_default */ 2325 /* */ 2326 /* <Description> */ 2327 /* This constant is deprecated. Please use @FT_KERNING_DEFAULT */ 2328 /* instead. */ 2329 /* */ 2330 #define ft_kerning_default FT_KERNING_DEFAULT 2331 2332 2333 /*************************************************************************/ 2334 /* */ 2335 /* <Const> */ 2336 /* ft_kerning_unfitted */ 2337 /* */ 2338 /* <Description> */ 2339 /* This constant is deprecated. Please use @FT_KERNING_UNFITTED */ 2340 /* instead. */ 2341 /* */ 2342 #define ft_kerning_unfitted FT_KERNING_UNFITTED 2343 2344 2345 /*************************************************************************/ 2346 /* */ 2347 /* <Const> */ 2348 /* ft_kerning_unscaled */ 2349 /* */ 2350 /* <Description> */ 2351 /* This constant is deprecated. Please use @FT_KERNING_UNSCALED */ 2352 /* instead. */ 2353 /* */ 2354 #define ft_kerning_unscaled FT_KERNING_UNSCALED 2355 2356 2357 /*************************************************************************/ 2358 /* */ 2359 /* <Function> */ 2360 /* FT_Get_Kerning */ 2361 /* */ 2362 /* <Description> */ 2363 /* Returns the kerning vector between two glyphs of a same face. */ 2364 /* */ 2365 /* <Input> */ 2366 /* face :: A handle to a source face object. */ 2367 /* */ 2368 /* left_glyph :: The index of the left glyph in the kern pair. */ 2369 /* */ 2370 /* right_glyph :: The index of the right glyph in the kern pair. */ 2371 /* */ 2372 /* kern_mode :: See @FT_Kerning_Mode for more information. */ 2373 /* Determines the scale/dimension of the returned */ 2374 /* kerning vector. */ 2375 /* */ 2376 /* <Output> */ 2377 /* akerning :: The kerning vector. This is in font units for */ 2378 /* scalable formats, and in pixels for fixed-sizes */ 2379 /* formats. */ 2380 /* */ 2381 /* <Return> */ 2382 /* FreeType error code. 0 means success. */ 2383 /* */ 2384 /* <Note> */ 2385 /* Only horizontal layouts (left-to-right & right-to-left) are */ 2386 /* supported by this method. Other layouts, or more sophisticated */ 2387 /* kernings, are out of the scope of this API function -- they can be */ 2388 /* implemented through format-specific interfaces. */ 2389 /* */ 2390 FT_EXPORT( FT_Error ) 2391 FT_Get_Kerning( FT_Face face, 2392 FT_UInt left_glyph, 2393 FT_UInt right_glyph, 2394 FT_UInt kern_mode, 2395 FT_Vector *akerning ); 2396 2397 2398 /*************************************************************************/ 2399 /* */ 2400 /* <Function> */ 2401 /* FT_Get_Glyph_Name */ 2402 /* */ 2403 /* <Description> */ 2404 /* Retrieves the ASCII name of a given glyph in a face. This only */ 2405 /* works for those faces where FT_HAS_GLYPH_NAME(face) returns true. */ 2406 /* */ 2407 /* <Input> */ 2408 /* face :: A handle to a source face object. */ 2409 /* */ 2410 /* glyph_index :: The glyph index. */ 2411 /* */ 2412 /* buffer_max :: The maximal number of bytes available in the */ 2413 /* buffer. */ 2414 /* */ 2415 /* <Output> */ 2416 /* buffer :: A pointer to a target buffer where the name will be */ 2417 /* copied to. */ 2418 /* */ 2419 /* <Return> */ 2420 /* FreeType error code. 0 means success. */ 2421 /* */ 2422 /* <Note> */ 2423 /* An error is returned if the face doesn't provide glyph names or if */ 2424 /* the glyph index is invalid. In all cases of failure, the first */ 2425 /* byte of `buffer' will be set to 0 to indicate an empty name. */ 2426 /* */ 2427 /* The glyph name is truncated to fit within the buffer if it is too */ 2428 /* long. The returned string is always zero-terminated. */ 2429 /* */ 2430 /* This function is not compiled within the library if the config */ 2431 /* macro FT_CONFIG_OPTION_NO_GLYPH_NAMES is defined in */ 2432 /* `include/freetype/config/ftoptions.h' */ 2433 /* */ 2434 FT_EXPORT( FT_Error ) 2435 FT_Get_Glyph_Name( FT_Face face, 2436 FT_UInt glyph_index, 2437 FT_Pointer buffer, 2438 FT_UInt buffer_max ); 2439 2440 2441 /*************************************************************************/ 2442 /* */ 2443 /* <Function> */ 2444 /* FT_Get_Postscript_Name */ 2445 /* */ 2446 /* <Description> */ 2447 /* Retrieves the ASCII Postscript name of a given face, if available. */ 2448 /* This should only work with Postscript and TrueType fonts. */ 2449 /* */ 2450 /* <Input> */ 2451 /* face :: A handle to the source face object. */ 2452 /* */ 2453 /* <Return> */ 2454 /* A pointer to the face's Postscript name. NULL if un-available. */ 2455 /* */ 2456 /* <Note> */ 2457 /* The returned pointer is owned by the face and will be destroyed */ 2458 /* with it. */ 2459 /* */ 2460 FT_EXPORT( const char* ) 2461 FT_Get_Postscript_Name( FT_Face face ); 2462 2463 2464 /*************************************************************************/ 2465 /* */ 2466 /* <Function> */ 2467 /* FT_Select_Charmap */ 2468 /* */ 2469 /* <Description> */ 2470 /* Selects a given charmap by its encoding tag (as listed in */ 2471 /* `freetype.h'). */ 2472 /* */ 2473 /* <InOut> */ 2474 /* face :: A handle to the source face object. */ 2475 /* */ 2476 /* <Input> */ 2477 /* encoding :: A handle to the selected charmap. */ 2478 /* */ 2479 /* <Return> */ 2480 /* FreeType error code. 0 means success. */ 2481 /* */ 2482 /* <Note> */ 2483 /* This function will return an error if no charmap in the face */ 2484 /* corresponds to the encoding queried here. */ 2485 /* */ 2486 FT_EXPORT( FT_Error ) 2487 FT_Select_Charmap( FT_Face face, 2488 FT_Encoding encoding ); 2489 2490 2491 /*************************************************************************/ 2492 /* */ 2493 /* <Function> */ 2494 /* FT_Set_Charmap */ 2495 /* */ 2496 /* <Description> */ 2497 /* Selects a given charmap for character code to glyph index */ 2498 /* decoding. */ 2499 /* */ 2500 /* <InOut> */ 2501 /* face :: A handle to the source face object. */ 2502 /* */ 2503 /* <Input> */ 2504 /* charmap :: A handle to the selected charmap. */ 2505 /* */ 2506 /* <Return> */ 2507 /* FreeType error code. 0 means success. */ 2508 /* */ 2509 /* <Note> */ 2510 /* This function will return an error if the charmap is not part of */ 2511 /* the face (i.e., if it is not listed in the face->charmaps[] */ 2512 /* table). */ 2513 /* */ 2514 FT_EXPORT( FT_Error ) 2515 FT_Set_Charmap( FT_Face face, 2516 FT_CharMap charmap ); 2517 2518 2519 /*************************************************************************/ 2520 /* */ 2521 /* <Function> */ 2522 /* FT_Get_Char_Index */ 2523 /* */ 2524 /* <Description> */ 2525 /* Returns the glyph index of a given character code. This function */ 2526 /* uses a charmap object to do the translation. */ 2527 /* */ 2528 /* <Input> */ 2529 /* face :: A handle to the source face object. */ 2530 /* */ 2531 /* charcode :: The character code. */ 2532 /* */ 2533 /* <Return> */ 2534 /* The glyph index. 0 means `undefined character code'. */ 2535 /* */ 2536 /* <Note> */ 2537 /* FreeType computes its own glyph indices which are not necessarily */ 2538 /* the same as used in the font in case the font is based on glyph */ 2539 /* indices. Reason for this behaviour is to assure that index 0 is */ 2540 /* never used, representing the missing glyph. */ 2541 /* */ 2542 FT_EXPORT( FT_UInt ) 2543 FT_Get_Char_Index( FT_Face face, 2544 FT_ULong charcode ); 2545 2546 2547 /*************************************************************************/ 2548 /* */ 2549 /* <Function> */ 2550 /* FT_Get_First_Char */ 2551 /* */ 2552 /* <Description> */ 2553 /* This function is used to return the first character code in the */ 2554 /* current charmap of a given face. It will also return the */ 2555 /* corresponding glyph index. */ 2556 /* */ 2557 /* <Input> */ 2558 /* face :: A handle to the source face object. */ 2559 /* */ 2560 /* <Output> */ 2561 /* agindex :: Glyph index of first character code. 0 if charmap is */ 2562 /* empty. */ 2563 /* */ 2564 /* <Return> */ 2565 /* The charmap's first character code. */ 2566 /* */ 2567 /* <Note> */ 2568 /* You should use this function with @FT_Get_Next_Char to be able to */ 2569 /* parse all character codes available in a given charmap. The code */ 2570 /* should look like this: */ 2571 /* */ 2572 /* { */ 2573 /* FT_ULong charcode; */ 2574 /* FT_UInt gindex; */ 2575 /* */ 2576 /* */ 2577 /* charcode = FT_Get_First_Char( face, &gindex ); */ 2578 /* while ( gindex != 0 ) */ 2579 /* { */ 2580 /* ... do something with (charcode,gindex) pair ... */ 2581 /* */ 2582 /* charcode = FT_Get_Next_Char( face, charcode, &gindex ); */ 2583 /* } */ 2584 /* } */ 2585 /* */ 2586 /* Note that `*agindex' will be set to 0 if the charmap is empty. */ 2587 /* The result itself can be 0 in two cases: if the charmap is empty */ 2588 /* or when the value 0 is the first valid character code. */ 2589 /* */ 2590 FT_EXPORT( FT_ULong ) 2591 FT_Get_First_Char( FT_Face face, 2592 FT_UInt *agindex ); 2593 2594 2595 /*************************************************************************/ 2596 /* */ 2597 /* <Function> */ 2598 /* FT_Get_Next_Char */ 2599 /* */ 2600 /* <Description> */ 2601 /* This function is used to return the next character code in the */ 2602 /* current charmap of a given face following the value 'char_code', */ 2603 /* as well as the corresponding glyph index. */ 2604 /* */ 2605 /* <Input> */ 2606 /* face :: A handle to the source face object. */ 2607 /* char_code :: The starting character code. */ 2608 /* */ 2609 /* <Output> */ 2610 /* agindex :: Glyph index of first character code. 0 if charmap */ 2611 /* is empty. */ 2612 /* */ 2613 /* <Return> */ 2614 /* The charmap's next character code. */ 2615 /* */ 2616 /* <Note> */ 2617 /* You should use this function with @FT_Get_First_Char to walk */ 2618 /* through all character codes available in a given charmap. See */ 2619 /* the note for this function for a simple code example. */ 2620 /* */ 2621 /* Note that `*agindex' will be set to 0 when there are no more codes */ 2622 /* in the charmap. */ 2623 /* */ 2624 FT_EXPORT( FT_ULong ) 2625 FT_Get_Next_Char( FT_Face face, 2626 FT_ULong char_code, 2627 FT_UInt *agindex ); 2628 2629 2630 /*************************************************************************/ 2631 /* */ 2632 /* <Function> */ 2633 /* FT_Get_Name_Index */ 2634 /* */ 2635 /* <Description> */ 2636 /* Returns the glyph index of a given glyph name. This function uses */ 2637 /* driver specific objects to do the translation. */ 2638 /* */ 2639 /* <Input> */ 2640 /* face :: A handle to the source face object. */ 2641 /* */ 2642 /* glyph_name :: The glyph name. */ 2643 /* */ 2644 /* <Return> */ 2645 /* The glyph index. 0 means `undefined character code'. */ 2646 /* */ 2647 FT_EXPORT( FT_UInt ) 2648 FT_Get_Name_Index( FT_Face face, 2649 FT_String* glyph_name ); 2650 2651 2652 2653 /*************************************************************************/ 2654 /* */ 2655 /* <Section> */ 2656 /* computations */ 2657 /* */ 2658 /* <Title> */ 2659 /* Computations */ 2660 /* */ 2661 /* <Abstract> */ 2662 /* Crunching fixed numbers and vectors */ 2663 /* */ 2664 /* <Description> */ 2665 /* This section contains various functions used to perform */ 2666 /* computations on 16.16 fixed-float numbers or 2d vectors. */ 2667 /* */ 2668 /* <Order> */ 2669 /* FT_MulDiv */ 2670 /* FT_MulFix */ 2671 /* FT_DivFix */ 2672 /* FT_RoundFix */ 2673 /* FT_CeilFix */ 2674 /* FT_FloorFix */ 2675 /* FT_Vector_Transform */ 2676 /* FT_Matrix_Multiply */ 2677 /* FT_Matrix_Invert */ 2678 /* */ 2679 /*************************************************************************/ 2680 2681 2682 /*************************************************************************/ 2683 /* */ 2684 /* <Function> */ 2685 /* FT_MulDiv */ 2686 /* */ 2687 /* <Description> */ 2688 /* A very simple function used to perform the computation `(a*b)/c' */ 2689 /* with maximal accuracy (it uses a 64-bit intermediate integer */ 2690 /* whenever necessary). */ 2691 /* */ 2692 /* This function isn't necessarily as fast as some processor specific */ 2693 /* operations, but is at least completely portable. */ 2694 /* */ 2695 /* <Input> */ 2696 /* a :: The first multiplier. */ 2697 /* b :: The second multiplier. */ 2698 /* c :: The divisor. */ 2699 /* */ 2700 /* <Return> */ 2701 /* The result of `(a*b)/c'. This function never traps when trying to */ 2702 /* divide by zero; it simply returns `MaxInt' or `MinInt' depending */ 2703 /* on the signs of `a' and `b'. */ 2704 /* */ 2705 FT_EXPORT( FT_Long ) 2706 FT_MulDiv( FT_Long a, 2707 FT_Long b, 2708 FT_Long c ); 2709 2710 2711 /*************************************************************************/ 2712 /* */ 2713 /* <Function> */ 2714 /* FT_MulFix */ 2715 /* */ 2716 /* <Description> */ 2717 /* A very simple function used to perform the computation */ 2718 /* `(a*b)/0x10000' with maximal accuracy. Most of the time this is */ 2719 /* used to multiply a given value by a 16.16 fixed float factor. */ 2720 /* */ 2721 /* <Input> */ 2722 /* a :: The first multiplier. */ 2723 /* b :: The second multiplier. Use a 16.16 factor here whenever */ 2724 /* possible (see note below). */ 2725 /* */ 2726 /* <Return> */ 2727 /* The result of `(a*b)/0x10000'. */ 2728 /* */ 2729 /* <Note> */ 2730 /* This function has been optimized for the case where the absolute */ 2731 /* value of `a' is less than 2048, and `b' is a 16.16 scaling factor. */ 2732 /* As this happens mainly when scaling from notional units to */ 2733 /* fractional pixels in FreeType, it resulted in noticeable speed */ 2734 /* improvements between versions 2.x and 1.x. */ 2735 /* */ 2736 /* As a conclusion, always try to place a 16.16 factor as the */ 2737 /* _second_ argument of this function; this can make a great */ 2738 /* difference. */ 2739 /* */ 2740 FT_EXPORT( FT_Long ) 2741 FT_MulFix( FT_Long a, 2742 FT_Long b ); 2743 2744 2745 /*************************************************************************/ 2746 /* */ 2747 /* <Function> */ 2748 /* FT_DivFix */ 2749 /* */ 2750 /* <Description> */ 2751 /* A very simple function used to perform the computation */ 2752 /* `(a*0x10000)/b' with maximal accuracy. Most of the time, this is */ 2753 /* used to divide a given value by a 16.16 fixed float factor. */ 2754 /* */ 2755 /* <Input> */ 2756 /* a :: The first multiplier. */ 2757 /* b :: The second multiplier. Use a 16.16 factor here whenever */ 2758 /* possible (see note below). */ 2759 /* */ 2760 /* <Return> */ 2761 /* The result of `(a*0x10000)/b'. */ 2762 /* */ 2763 /* <Note> */ 2764 /* The optimization for FT_DivFix() is simple: If (a << 16) fits in */ 2765 /* 32 bits, then the division is computed directly. Otherwise, we */ 2766 /* use a specialized version of the old @FT_MulDiv64. */ 2767 /* */ 2768 FT_EXPORT( FT_Long ) 2769 FT_DivFix( FT_Long a, 2770 FT_Long b ); 2771 2772 2773 /*************************************************************************/ 2774 /* */ 2775 /* <Function> */ 2776 /* FT_RoundFix */ 2777 /* */ 2778 /* <Description> */ 2779 /* A very simple function used to round a 16.16 fixed number. */ 2780 /* */ 2781 /* <Input> */ 2782 /* a :: The number to be rounded. */ 2783 /* */ 2784 /* <Return> */ 2785 /* The result of `(a + 0x8000) & -0x10000'. */ 2786 /* */ 2787 FT_EXPORT( FT_Fixed ) 2788 FT_RoundFix( FT_Fixed a ); 2789 2790 2791 /*************************************************************************/ 2792 /* */ 2793 /* <Function> */ 2794 /* FT_CeilFix */ 2795 /* */ 2796 /* <Description> */ 2797 /* A very simple function used to compute the ceiling function of a */ 2798 /* 16.16 fixed number. */ 2799 /* */ 2800 /* <Input> */ 2801 /* a :: The number for which the ceiling function is to be computed. */ 2802 /* */ 2803 /* <Return> */ 2804 /* The result of `(a + 0x10000 - 1) & -0x10000'. */ 2805 /* */ 2806 FT_EXPORT( FT_Fixed ) 2807 FT_CeilFix( FT_Fixed a ); 2808 2809 2810 /*************************************************************************/ 2811 /* */ 2812 /* <Function> */ 2813 /* FT_FloorFix */ 2814 /* */ 2815 /* <Description> */ 2816 /* A very simple function used to compute the floor function of a */ 2817 /* 16.16 fixed number. */ 2818 /* */ 2819 /* <Input> */ 2820 /* a :: The number for which the floor function is to be computed. */ 2821 /* */ 2822 /* <Return> */ 2823 /* The result of `a & -0x10000'. */ 2824 /* */ 2825 FT_EXPORT( FT_Fixed ) 2826 FT_FloorFix( FT_Fixed a ); 2827 2828 2829 /*************************************************************************/ 2830 /* */ 2831 /* <Function> */ 2832 /* FT_Vector_Transform */ 2833 /* */ 2834 /* <Description> */ 2835 /* Transforms a single vector through a 2x2 matrix. */ 2836 /* */ 2837 /* <InOut> */ 2838 /* vector :: The target vector to transform. */ 2839 /* */ 2840 /* <Input> */ 2841 /* matrix :: A pointer to the source 2x2 matrix. */ 2842 /* */ 2843 /* <Note> */ 2844 /* The result is undefined if either `vector' or `matrix' is invalid. */ 2845 /* */ 2846 FT_EXPORT( void ) 2847 FT_Vector_Transform( FT_Vector* vec, 2848 FT_Matrix* matrix ); 2849 2850 2851 /* */ 2852 2853 2854 FT_END_HEADER 2855 2856 #endif /* __FREETYPE_H__ */ 2857 2858 2859 /* END */ 2860 2861