1 /***************************************************************************/ 2 /* */ 3 /* ftcache.h */ 4 /* */ 5 /* FreeType Cache subsystem (specification). */ 6 /* */ 7 /* Copyright 1996-2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2010 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 __FTCACHE_H__ 20 #define __FTCACHE_H__ 21 22 23 #include <ft2build.h> 24 #include FT_GLYPH_H 25 26 27 FT_BEGIN_HEADER 28 29 30 /************************************************************************* 31 * 32 * <Section> 33 * cache_subsystem 34 * 35 * <Title> 36 * Cache Sub-System 37 * 38 * <Abstract> 39 * How to cache face, size, and glyph data with FreeType~2. 40 * 41 * <Description> 42 * This section describes the FreeType~2 cache sub-system, which is used 43 * to limit the number of concurrently opened @FT_Face and @FT_Size 44 * objects, as well as caching information like character maps and glyph 45 * images while limiting their maximum memory usage. 46 * 47 * Note that all types and functions begin with the `FTC_' prefix. 48 * 49 * The cache is highly portable and thus doesn't know anything about the 50 * fonts installed on your system, or how to access them. This implies 51 * the following scheme: 52 * 53 * First, available or installed font faces are uniquely identified by 54 * @FTC_FaceID values, provided to the cache by the client. Note that 55 * the cache only stores and compares these values, and doesn't try to 56 * interpret them in any way. 57 * 58 * Second, the cache calls, only when needed, a client-provided function 59 * to convert an @FTC_FaceID into a new @FT_Face object. The latter is 60 * then completely managed by the cache, including its termination 61 * through @FT_Done_Face. To monitor termination of face objects, the 62 * finalizer callback in the `generic' field of the @FT_Face object can 63 * be used, which might also be used to store the @FTC_FaceID of the 64 * face. 65 * 66 * Clients are free to map face IDs to anything else. The most simple 67 * usage is to associate them to a (pathname,face_index) pair that is 68 * used to call @FT_New_Face. However, more complex schemes are also 69 * possible. 70 * 71 * Note that for the cache to work correctly, the face ID values must be 72 * *persistent*, which means that the contents they point to should not 73 * change at runtime, or that their value should not become invalid. 74 * 75 * If this is unavoidable (e.g., when a font is uninstalled at runtime), 76 * you should call @FTC_Manager_RemoveFaceID as soon as possible, to let 77 * the cache get rid of any references to the old @FTC_FaceID it may 78 * keep internally. Failure to do so will lead to incorrect behaviour 79 * or even crashes. 80 * 81 * To use the cache, start with calling @FTC_Manager_New to create a new 82 * @FTC_Manager object, which models a single cache instance. You can 83 * then look up @FT_Face and @FT_Size objects with 84 * @FTC_Manager_LookupFace and @FTC_Manager_LookupSize, respectively. 85 * 86 * If you want to use the charmap caching, call @FTC_CMapCache_New, then 87 * later use @FTC_CMapCache_Lookup to perform the equivalent of 88 * @FT_Get_Char_Index, only much faster. 89 * 90 * If you want to use the @FT_Glyph caching, call @FTC_ImageCache, then 91 * later use @FTC_ImageCache_Lookup to retrieve the corresponding 92 * @FT_Glyph objects from the cache. 93 * 94 * If you need lots of small bitmaps, it is much more memory efficient 95 * to call @FTC_SBitCache_New followed by @FTC_SBitCache_Lookup. This 96 * returns @FTC_SBitRec structures, which are used to store small 97 * bitmaps directly. (A small bitmap is one whose metrics and 98 * dimensions all fit into 8-bit integers). 99 * 100 * We hope to also provide a kerning cache in the near future. 101 * 102 * 103 * <Order> 104 * FTC_Manager 105 * FTC_FaceID 106 * FTC_Face_Requester 107 * 108 * FTC_Manager_New 109 * FTC_Manager_Reset 110 * FTC_Manager_Done 111 * FTC_Manager_LookupFace 112 * FTC_Manager_LookupSize 113 * FTC_Manager_RemoveFaceID 114 * 115 * FTC_Node 116 * FTC_Node_Unref 117 * 118 * FTC_ImageCache 119 * FTC_ImageCache_New 120 * FTC_ImageCache_Lookup 121 * 122 * FTC_SBit 123 * FTC_SBitCache 124 * FTC_SBitCache_New 125 * FTC_SBitCache_Lookup 126 * 127 * FTC_CMapCache 128 * FTC_CMapCache_New 129 * FTC_CMapCache_Lookup 130 * 131 *************************************************************************/ 132 133 134 /*************************************************************************/ 135 /*************************************************************************/ 136 /*************************************************************************/ 137 /***** *****/ 138 /***** BASIC TYPE DEFINITIONS *****/ 139 /***** *****/ 140 /*************************************************************************/ 141 /*************************************************************************/ 142 /*************************************************************************/ 143 144 145 /************************************************************************* 146 * 147 * @type: FTC_FaceID 148 * 149 * @description: 150 * An opaque pointer type that is used to identity face objects. The 151 * contents of such objects is application-dependent. 152 * 153 * These pointers are typically used to point to a user-defined 154 * structure containing a font file path, and face index. 155 * 156 * @note: 157 * Never use NULL as a valid @FTC_FaceID. 158 * 159 * Face IDs are passed by the client to the cache manager, which calls, 160 * when needed, the @FTC_Face_Requester to translate them into new 161 * @FT_Face objects. 162 * 163 * If the content of a given face ID changes at runtime, or if the value 164 * becomes invalid (e.g., when uninstalling a font), you should 165 * immediately call @FTC_Manager_RemoveFaceID before any other cache 166 * function. 167 * 168 * Failure to do so will result in incorrect behaviour or even 169 * memory leaks and crashes. 170 */ 171 typedef FT_Pointer FTC_FaceID; 172 173 174 /************************************************************************ 175 * 176 * @functype: 177 * FTC_Face_Requester 178 * 179 * @description: 180 * A callback function provided by client applications. It is used by 181 * the cache manager to translate a given @FTC_FaceID into a new valid 182 * @FT_Face object, on demand. 183 * 184 * <Input> 185 * face_id :: 186 * The face ID to resolve. 187 * 188 * library :: 189 * A handle to a FreeType library object. 190 * 191 * req_data :: 192 * Application-provided request data (see note below). 193 * 194 * <Output> 195 * aface :: 196 * A new @FT_Face handle. 197 * 198 * <Return> 199 * FreeType error code. 0~means success. 200 * 201 * <Note> 202 * The third parameter `req_data' is the same as the one passed by the 203 * client when @FTC_Manager_New is called. 204 * 205 * The face requester should not perform funny things on the returned 206 * face object, like creating a new @FT_Size for it, or setting a 207 * transformation through @FT_Set_Transform! 208 */ 209 typedef FT_Error 210 (*FTC_Face_Requester)( FTC_FaceID face_id, 211 FT_Library library, 212 FT_Pointer request_data, 213 FT_Face* aface ); 214 215 /* */ 216 217 #ifdef FT_CONFIG_OPTION_OLD_INTERNALS 218 219 /* these macros are incompatible with LLP64, should not be used */ 220 221 #define FT_POINTER_TO_ULONG( p ) ( (FT_ULong)(FT_Pointer)(p) ) 222 223 #define FTC_FACE_ID_HASH( i ) \ 224 ((FT_UInt32)(( FT_POINTER_TO_ULONG( i ) >> 3 ) ^ \ 225 ( FT_POINTER_TO_ULONG( i ) << 7 ) ) ) 226 227 #endif /* FT_CONFIG_OPTION_OLD_INTERNALS */ 228 229 /*************************************************************************/ 230 /*************************************************************************/ 231 /*************************************************************************/ 232 /***** *****/ 233 /***** CACHE MANAGER OBJECT *****/ 234 /***** *****/ 235 /*************************************************************************/ 236 /*************************************************************************/ 237 /*************************************************************************/ 238 239 240 /*************************************************************************/ 241 /* */ 242 /* <Type> */ 243 /* FTC_Manager */ 244 /* */ 245 /* <Description> */ 246 /* This object corresponds to one instance of the cache-subsystem. */ 247 /* It is used to cache one or more @FT_Face objects, along with */ 248 /* corresponding @FT_Size objects. */ 249 /* */ 250 /* The manager intentionally limits the total number of opened */ 251 /* @FT_Face and @FT_Size objects to control memory usage. See the */ 252 /* `max_faces' and `max_sizes' parameters of @FTC_Manager_New. */ 253 /* */ 254 /* The manager is also used to cache `nodes' of various types while */ 255 /* limiting their total memory usage. */ 256 /* */ 257 /* All limitations are enforced by keeping lists of managed objects */ 258 /* in most-recently-used order, and flushing old nodes to make room */ 259 /* for new ones. */ 260 /* */ 261 typedef struct FTC_ManagerRec_* FTC_Manager; 262 263 264 /*************************************************************************/ 265 /* */ 266 /* <Type> */ 267 /* FTC_Node */ 268 /* */ 269 /* <Description> */ 270 /* An opaque handle to a cache node object. Each cache node is */ 271 /* reference-counted. A node with a count of~0 might be flushed */ 272 /* out of a full cache whenever a lookup request is performed. */ 273 /* */ 274 /* If you look up nodes, you have the ability to `acquire' them, */ 275 /* i.e., to increment their reference count. This will prevent the */ 276 /* node from being flushed out of the cache until you explicitly */ 277 /* `release' it (see @FTC_Node_Unref). */ 278 /* */ 279 /* See also @FTC_SBitCache_Lookup and @FTC_ImageCache_Lookup. */ 280 /* */ 281 typedef struct FTC_NodeRec_* FTC_Node; 282 283 284 /*************************************************************************/ 285 /* */ 286 /* <Function> */ 287 /* FTC_Manager_New */ 288 /* */ 289 /* <Description> */ 290 /* Create a new cache manager. */ 291 /* */ 292 /* <Input> */ 293 /* library :: The parent FreeType library handle to use. */ 294 /* */ 295 /* max_faces :: Maximum number of opened @FT_Face objects managed by */ 296 /* this cache instance. Use~0 for defaults. */ 297 /* */ 298 /* max_sizes :: Maximum number of opened @FT_Size objects managed by */ 299 /* this cache instance. Use~0 for defaults. */ 300 /* */ 301 /* max_bytes :: Maximum number of bytes to use for cached data nodes. */ 302 /* Use~0 for defaults. Note that this value does not */ 303 /* account for managed @FT_Face and @FT_Size objects. */ 304 /* */ 305 /* requester :: An application-provided callback used to translate */ 306 /* face IDs into real @FT_Face objects. */ 307 /* */ 308 /* req_data :: A generic pointer that is passed to the requester */ 309 /* each time it is called (see @FTC_Face_Requester). */ 310 /* */ 311 /* <Output> */ 312 /* amanager :: A handle to a new manager object. 0~in case of */ 313 /* failure. */ 314 /* */ 315 /* <Return> */ 316 /* FreeType error code. 0~means success. */ 317 /* */ 318 FT_EXPORT( FT_Error ) 319 FTC_Manager_New( FT_Library library, 320 FT_UInt max_faces, 321 FT_UInt max_sizes, 322 FT_ULong max_bytes, 323 FTC_Face_Requester requester, 324 FT_Pointer req_data, 325 FTC_Manager *amanager ); 326 327 328 /*************************************************************************/ 329 /* */ 330 /* <Function> */ 331 /* FTC_Manager_Reset */ 332 /* */ 333 /* <Description> */ 334 /* Empty a given cache manager. This simply gets rid of all the */ 335 /* currently cached @FT_Face and @FT_Size objects within the manager. */ 336 /* */ 337 /* <InOut> */ 338 /* manager :: A handle to the manager. */ 339 /* */ 340 FT_EXPORT( void ) 341 FTC_Manager_Reset( FTC_Manager manager ); 342 343 344 /*************************************************************************/ 345 /* */ 346 /* <Function> */ 347 /* FTC_Manager_Done */ 348 /* */ 349 /* <Description> */ 350 /* Destroy a given manager after emptying it. */ 351 /* */ 352 /* <Input> */ 353 /* manager :: A handle to the target cache manager object. */ 354 /* */ 355 FT_EXPORT( void ) 356 FTC_Manager_Done( FTC_Manager manager ); 357 358 359 /*************************************************************************/ 360 /* */ 361 /* <Function> */ 362 /* FTC_Manager_LookupFace */ 363 /* */ 364 /* <Description> */ 365 /* Retrieve the @FT_Face object that corresponds to a given face ID */ 366 /* through a cache manager. */ 367 /* */ 368 /* <Input> */ 369 /* manager :: A handle to the cache manager. */ 370 /* */ 371 /* face_id :: The ID of the face object. */ 372 /* */ 373 /* <Output> */ 374 /* aface :: A handle to the face object. */ 375 /* */ 376 /* <Return> */ 377 /* FreeType error code. 0~means success. */ 378 /* */ 379 /* <Note> */ 380 /* The returned @FT_Face object is always owned by the manager. You */ 381 /* should never try to discard it yourself. */ 382 /* */ 383 /* The @FT_Face object doesn't necessarily have a current size object */ 384 /* (i.e., face->size can be 0). If you need a specific `font size', */ 385 /* use @FTC_Manager_LookupSize instead. */ 386 /* */ 387 /* Never change the face's transformation matrix (i.e., never call */ 388 /* the @FT_Set_Transform function) on a returned face! If you need */ 389 /* to transform glyphs, do it yourself after glyph loading. */ 390 /* */ 391 /* When you perform a lookup, out-of-memory errors are detected */ 392 /* _within_ the lookup and force incremental flushes of the cache */ 393 /* until enough memory is released for the lookup to succeed. */ 394 /* */ 395 /* If a lookup fails with `FT_Err_Out_Of_Memory' the cache has */ 396 /* already been completely flushed, and still no memory was available */ 397 /* for the operation. */ 398 /* */ 399 FT_EXPORT( FT_Error ) 400 FTC_Manager_LookupFace( FTC_Manager manager, 401 FTC_FaceID face_id, 402 FT_Face *aface ); 403 404 405 /*************************************************************************/ 406 /* */ 407 /* <Struct> */ 408 /* FTC_ScalerRec */ 409 /* */ 410 /* <Description> */ 411 /* A structure used to describe a given character size in either */ 412 /* pixels or points to the cache manager. See */ 413 /* @FTC_Manager_LookupSize. */ 414 /* */ 415 /* <Fields> */ 416 /* face_id :: The source face ID. */ 417 /* */ 418 /* width :: The character width. */ 419 /* */ 420 /* height :: The character height. */ 421 /* */ 422 /* pixel :: A Boolean. If 1, the `width' and `height' fields are */ 423 /* interpreted as integer pixel character sizes. */ 424 /* Otherwise, they are expressed as 1/64th of points. */ 425 /* */ 426 /* x_res :: Only used when `pixel' is value~0 to indicate the */ 427 /* horizontal resolution in dpi. */ 428 /* */ 429 /* y_res :: Only used when `pixel' is value~0 to indicate the */ 430 /* vertical resolution in dpi. */ 431 /* */ 432 /* <Note> */ 433 /* This type is mainly used to retrieve @FT_Size objects through the */ 434 /* cache manager. */ 435 /* */ 436 typedef struct FTC_ScalerRec_ 437 { 438 FTC_FaceID face_id; 439 FT_UInt width; 440 FT_UInt height; 441 FT_Int pixel; 442 FT_UInt x_res; 443 FT_UInt y_res; 444 445 } FTC_ScalerRec; 446 447 448 /*************************************************************************/ 449 /* */ 450 /* <Struct> */ 451 /* FTC_Scaler */ 452 /* */ 453 /* <Description> */ 454 /* A handle to an @FTC_ScalerRec structure. */ 455 /* */ 456 typedef struct FTC_ScalerRec_* FTC_Scaler; 457 458 459 /*************************************************************************/ 460 /* */ 461 /* <Function> */ 462 /* FTC_Manager_LookupSize */ 463 /* */ 464 /* <Description> */ 465 /* Retrieve the @FT_Size object that corresponds to a given */ 466 /* @FTC_ScalerRec pointer through a cache manager. */ 467 /* */ 468 /* <Input> */ 469 /* manager :: A handle to the cache manager. */ 470 /* */ 471 /* scaler :: A scaler handle. */ 472 /* */ 473 /* <Output> */ 474 /* asize :: A handle to the size object. */ 475 /* */ 476 /* <Return> */ 477 /* FreeType error code. 0~means success. */ 478 /* */ 479 /* <Note> */ 480 /* The returned @FT_Size object is always owned by the manager. You */ 481 /* should never try to discard it by yourself. */ 482 /* */ 483 /* You can access the parent @FT_Face object simply as `size->face' */ 484 /* if you need it. Note that this object is also owned by the */ 485 /* manager. */ 486 /* */ 487 /* <Note> */ 488 /* When you perform a lookup, out-of-memory errors are detected */ 489 /* _within_ the lookup and force incremental flushes of the cache */ 490 /* until enough memory is released for the lookup to succeed. */ 491 /* */ 492 /* If a lookup fails with `FT_Err_Out_Of_Memory' the cache has */ 493 /* already been completely flushed, and still no memory is available */ 494 /* for the operation. */ 495 /* */ 496 FT_EXPORT( FT_Error ) 497 FTC_Manager_LookupSize( FTC_Manager manager, 498 FTC_Scaler scaler, 499 FT_Size *asize ); 500 501 502 /*************************************************************************/ 503 /* */ 504 /* <Function> */ 505 /* FTC_Node_Unref */ 506 /* */ 507 /* <Description> */ 508 /* Decrement a cache node's internal reference count. When the count */ 509 /* reaches 0, it is not destroyed but becomes eligible for subsequent */ 510 /* cache flushes. */ 511 /* */ 512 /* <Input> */ 513 /* node :: The cache node handle. */ 514 /* */ 515 /* manager :: The cache manager handle. */ 516 /* */ 517 FT_EXPORT( void ) 518 FTC_Node_Unref( FTC_Node node, 519 FTC_Manager manager ); 520 521 522 /************************************************************************* 523 * 524 * @function: 525 * FTC_Manager_RemoveFaceID 526 * 527 * @description: 528 * A special function used to indicate to the cache manager that 529 * a given @FTC_FaceID is no longer valid, either because its 530 * content changed, or because it was deallocated or uninstalled. 531 * 532 * @input: 533 * manager :: 534 * The cache manager handle. 535 * 536 * face_id :: 537 * The @FTC_FaceID to be removed. 538 * 539 * @note: 540 * This function flushes all nodes from the cache corresponding to this 541 * `face_id', with the exception of nodes with a non-null reference 542 * count. 543 * 544 * Such nodes are however modified internally so as to never appear 545 * in later lookups with the same `face_id' value, and to be immediately 546 * destroyed when released by all their users. 547 * 548 */ 549 FT_EXPORT( void ) 550 FTC_Manager_RemoveFaceID( FTC_Manager manager, 551 FTC_FaceID face_id ); 552 553 554 /*************************************************************************/ 555 /* */ 556 /* <Section> */ 557 /* cache_subsystem */ 558 /* */ 559 /*************************************************************************/ 560 561 /************************************************************************* 562 * 563 * @type: 564 * FTC_CMapCache 565 * 566 * @description: 567 * An opaque handle used to model a charmap cache. This cache is to 568 * hold character codes -> glyph indices mappings. 569 * 570 */ 571 typedef struct FTC_CMapCacheRec_* FTC_CMapCache; 572 573 574 /************************************************************************* 575 * 576 * @function: 577 * FTC_CMapCache_New 578 * 579 * @description: 580 * Create a new charmap cache. 581 * 582 * @input: 583 * manager :: 584 * A handle to the cache manager. 585 * 586 * @output: 587 * acache :: 588 * A new cache handle. NULL in case of error. 589 * 590 * @return: 591 * FreeType error code. 0~means success. 592 * 593 * @note: 594 * Like all other caches, this one will be destroyed with the cache 595 * manager. 596 * 597 */ 598 FT_EXPORT( FT_Error ) 599 FTC_CMapCache_New( FTC_Manager manager, 600 FTC_CMapCache *acache ); 601 602 603 /************************************************************************ 604 * 605 * @function: 606 * FTC_CMapCache_Lookup 607 * 608 * @description: 609 * Translate a character code into a glyph index, using the charmap 610 * cache. 611 * 612 * @input: 613 * cache :: 614 * A charmap cache handle. 615 * 616 * face_id :: 617 * The source face ID. 618 * 619 * cmap_index :: 620 * The index of the charmap in the source face. Any negative value 621 * means to use the cache @FT_Face's default charmap. 622 * 623 * char_code :: 624 * The character code (in the corresponding charmap). 625 * 626 * @return: 627 * Glyph index. 0~means `no glyph'. 628 * 629 */ 630 FT_EXPORT( FT_UInt ) 631 FTC_CMapCache_Lookup( FTC_CMapCache cache, 632 FTC_FaceID face_id, 633 FT_Int cmap_index, 634 FT_UInt32 char_code ); 635 636 637 /*************************************************************************/ 638 /* */ 639 /* <Section> */ 640 /* cache_subsystem */ 641 /* */ 642 /*************************************************************************/ 643 644 645 /*************************************************************************/ 646 /*************************************************************************/ 647 /*************************************************************************/ 648 /***** *****/ 649 /***** IMAGE CACHE OBJECT *****/ 650 /***** *****/ 651 /*************************************************************************/ 652 /*************************************************************************/ 653 /*************************************************************************/ 654 655 656 /************************************************************************* 657 * 658 * @struct: 659 * FTC_ImageTypeRec 660 * 661 * @description: 662 * A structure used to model the type of images in a glyph cache. 663 * 664 * @fields: 665 * face_id :: 666 * The face ID. 667 * 668 * width :: 669 * The width in pixels. 670 * 671 * height :: 672 * The height in pixels. 673 * 674 * flags :: 675 * The load flags, as in @FT_Load_Glyph. 676 * 677 */ 678 typedef struct FTC_ImageTypeRec_ 679 { 680 FTC_FaceID face_id; 681 FT_Int width; 682 FT_Int height; 683 FT_Int32 flags; 684 685 } FTC_ImageTypeRec; 686 687 688 /************************************************************************* 689 * 690 * @type: 691 * FTC_ImageType 692 * 693 * @description: 694 * A handle to an @FTC_ImageTypeRec structure. 695 * 696 */ 697 typedef struct FTC_ImageTypeRec_* FTC_ImageType; 698 699 700 /* */ 701 702 703 #define FTC_IMAGE_TYPE_COMPARE( d1, d2 ) \ 704 ( (d1)->face_id == (d2)->face_id && \ 705 (d1)->width == (d2)->width && \ 706 (d1)->flags == (d2)->flags ) 707 708 #ifdef FT_CONFIG_OPTION_OLD_INTERNALS 709 710 /* this macro is incompatible with LLP64, should not be used */ 711 712 #define FTC_IMAGE_TYPE_HASH( d ) \ 713 (FT_UFast)( FTC_FACE_ID_HASH( (d)->face_id ) ^ \ 714 ( (d)->width << 8 ) ^ (d)->height ^ \ 715 ( (d)->flags << 4 ) ) 716 717 #endif /* FT_CONFIG_OPTION_OLD_INTERNALS */ 718 719 720 /*************************************************************************/ 721 /* */ 722 /* <Type> */ 723 /* FTC_ImageCache */ 724 /* */ 725 /* <Description> */ 726 /* A handle to an glyph image cache object. They are designed to */ 727 /* hold many distinct glyph images while not exceeding a certain */ 728 /* memory threshold. */ 729 /* */ 730 typedef struct FTC_ImageCacheRec_* FTC_ImageCache; 731 732 733 /*************************************************************************/ 734 /* */ 735 /* <Function> */ 736 /* FTC_ImageCache_New */ 737 /* */ 738 /* <Description> */ 739 /* Create a new glyph image cache. */ 740 /* */ 741 /* <Input> */ 742 /* manager :: The parent manager for the image cache. */ 743 /* */ 744 /* <Output> */ 745 /* acache :: A handle to the new glyph image cache object. */ 746 /* */ 747 /* <Return> */ 748 /* FreeType error code. 0~means success. */ 749 /* */ 750 FT_EXPORT( FT_Error ) 751 FTC_ImageCache_New( FTC_Manager manager, 752 FTC_ImageCache *acache ); 753 754 755 /*************************************************************************/ 756 /* */ 757 /* <Function> */ 758 /* FTC_ImageCache_Lookup */ 759 /* */ 760 /* <Description> */ 761 /* Retrieve a given glyph image from a glyph image cache. */ 762 /* */ 763 /* <Input> */ 764 /* cache :: A handle to the source glyph image cache. */ 765 /* */ 766 /* type :: A pointer to a glyph image type descriptor. */ 767 /* */ 768 /* gindex :: The glyph index to retrieve. */ 769 /* */ 770 /* <Output> */ 771 /* aglyph :: The corresponding @FT_Glyph object. 0~in case of */ 772 /* failure. */ 773 /* */ 774 /* anode :: Used to return the address of of the corresponding cache */ 775 /* node after incrementing its reference count (see note */ 776 /* below). */ 777 /* */ 778 /* <Return> */ 779 /* FreeType error code. 0~means success. */ 780 /* */ 781 /* <Note> */ 782 /* The returned glyph is owned and managed by the glyph image cache. */ 783 /* Never try to transform or discard it manually! You can however */ 784 /* create a copy with @FT_Glyph_Copy and modify the new one. */ 785 /* */ 786 /* If `anode' is _not_ NULL, it receives the address of the cache */ 787 /* node containing the glyph image, after increasing its reference */ 788 /* count. This ensures that the node (as well as the @FT_Glyph) will */ 789 /* always be kept in the cache until you call @FTC_Node_Unref to */ 790 /* `release' it. */ 791 /* */ 792 /* If `anode' is NULL, the cache node is left unchanged, which means */ 793 /* that the @FT_Glyph could be flushed out of the cache on the next */ 794 /* call to one of the caching sub-system APIs. Don't assume that it */ 795 /* is persistent! */ 796 /* */ 797 FT_EXPORT( FT_Error ) 798 FTC_ImageCache_Lookup( FTC_ImageCache cache, 799 FTC_ImageType type, 800 FT_UInt gindex, 801 FT_Glyph *aglyph, 802 FTC_Node *anode ); 803 804 805 /*************************************************************************/ 806 /* */ 807 /* <Function> */ 808 /* FTC_ImageCache_LookupScaler */ 809 /* */ 810 /* <Description> */ 811 /* A variant of @FTC_ImageCache_Lookup that uses an @FTC_ScalerRec */ 812 /* to specify the face ID and its size. */ 813 /* */ 814 /* <Input> */ 815 /* cache :: A handle to the source glyph image cache. */ 816 /* */ 817 /* scaler :: A pointer to a scaler descriptor. */ 818 /* */ 819 /* load_flags :: The corresponding load flags. */ 820 /* */ 821 /* gindex :: The glyph index to retrieve. */ 822 /* */ 823 /* <Output> */ 824 /* aglyph :: The corresponding @FT_Glyph object. 0~in case of */ 825 /* failure. */ 826 /* */ 827 /* anode :: Used to return the address of of the corresponding */ 828 /* cache node after incrementing its reference count */ 829 /* (see note below). */ 830 /* */ 831 /* <Return> */ 832 /* FreeType error code. 0~means success. */ 833 /* */ 834 /* <Note> */ 835 /* The returned glyph is owned and managed by the glyph image cache. */ 836 /* Never try to transform or discard it manually! You can however */ 837 /* create a copy with @FT_Glyph_Copy and modify the new one. */ 838 /* */ 839 /* If `anode' is _not_ NULL, it receives the address of the cache */ 840 /* node containing the glyph image, after increasing its reference */ 841 /* count. This ensures that the node (as well as the @FT_Glyph) will */ 842 /* always be kept in the cache until you call @FTC_Node_Unref to */ 843 /* `release' it. */ 844 /* */ 845 /* If `anode' is NULL, the cache node is left unchanged, which means */ 846 /* that the @FT_Glyph could be flushed out of the cache on the next */ 847 /* call to one of the caching sub-system APIs. Don't assume that it */ 848 /* is persistent! */ 849 /* */ 850 /* Calls to @FT_Set_Char_Size and friends have no effect on cached */ 851 /* glyphs; you should always use the FreeType cache API instead. */ 852 /* */ 853 FT_EXPORT( FT_Error ) 854 FTC_ImageCache_LookupScaler( FTC_ImageCache cache, 855 FTC_Scaler scaler, 856 FT_ULong load_flags, 857 FT_UInt gindex, 858 FT_Glyph *aglyph, 859 FTC_Node *anode ); 860 861 862 /*************************************************************************/ 863 /* */ 864 /* <Type> */ 865 /* FTC_SBit */ 866 /* */ 867 /* <Description> */ 868 /* A handle to a small bitmap descriptor. See the @FTC_SBitRec */ 869 /* structure for details. */ 870 /* */ 871 typedef struct FTC_SBitRec_* FTC_SBit; 872 873 874 /*************************************************************************/ 875 /* */ 876 /* <Struct> */ 877 /* FTC_SBitRec */ 878 /* */ 879 /* <Description> */ 880 /* A very compact structure used to describe a small glyph bitmap. */ 881 /* */ 882 /* <Fields> */ 883 /* width :: The bitmap width in pixels. */ 884 /* */ 885 /* height :: The bitmap height in pixels. */ 886 /* */ 887 /* left :: The horizontal distance from the pen position to the */ 888 /* left bitmap border (a.k.a. `left side bearing', or */ 889 /* `lsb'). */ 890 /* */ 891 /* top :: The vertical distance from the pen position (on the */ 892 /* baseline) to the upper bitmap border (a.k.a. `top */ 893 /* side bearing'). The distance is positive for upwards */ 894 /* y~coordinates. */ 895 /* */ 896 /* format :: The format of the glyph bitmap (monochrome or gray). */ 897 /* */ 898 /* max_grays :: Maximum gray level value (in the range 1 to~255). */ 899 /* */ 900 /* pitch :: The number of bytes per bitmap line. May be positive */ 901 /* or negative. */ 902 /* */ 903 /* xadvance :: The horizontal advance width in pixels. */ 904 /* */ 905 /* yadvance :: The vertical advance height in pixels. */ 906 /* */ 907 /* buffer :: A pointer to the bitmap pixels. */ 908 /* */ 909 typedef struct FTC_SBitRec_ 910 { 911 FT_Byte width; 912 FT_Byte height; 913 FT_Char left; 914 FT_Char top; 915 916 FT_Byte format; 917 FT_Byte max_grays; 918 FT_Short pitch; 919 FT_Char xadvance; 920 FT_Char yadvance; 921 922 FT_Byte* buffer; 923 924 } FTC_SBitRec; 925 926 927 /*************************************************************************/ 928 /* */ 929 /* <Type> */ 930 /* FTC_SBitCache */ 931 /* */ 932 /* <Description> */ 933 /* A handle to a small bitmap cache. These are special cache objects */ 934 /* used to store small glyph bitmaps (and anti-aliased pixmaps) in a */ 935 /* much more efficient way than the traditional glyph image cache */ 936 /* implemented by @FTC_ImageCache. */ 937 /* */ 938 typedef struct FTC_SBitCacheRec_* FTC_SBitCache; 939 940 941 /*************************************************************************/ 942 /* */ 943 /* <Function> */ 944 /* FTC_SBitCache_New */ 945 /* */ 946 /* <Description> */ 947 /* Create a new cache to store small glyph bitmaps. */ 948 /* */ 949 /* <Input> */ 950 /* manager :: A handle to the source cache manager. */ 951 /* */ 952 /* <Output> */ 953 /* acache :: A handle to the new sbit cache. NULL in case of error. */ 954 /* */ 955 /* <Return> */ 956 /* FreeType error code. 0~means success. */ 957 /* */ 958 FT_EXPORT( FT_Error ) 959 FTC_SBitCache_New( FTC_Manager manager, 960 FTC_SBitCache *acache ); 961 962 963 /*************************************************************************/ 964 /* */ 965 /* <Function> */ 966 /* FTC_SBitCache_Lookup */ 967 /* */ 968 /* <Description> */ 969 /* Look up a given small glyph bitmap in a given sbit cache and */ 970 /* `lock' it to prevent its flushing from the cache until needed. */ 971 /* */ 972 /* <Input> */ 973 /* cache :: A handle to the source sbit cache. */ 974 /* */ 975 /* type :: A pointer to the glyph image type descriptor. */ 976 /* */ 977 /* gindex :: The glyph index. */ 978 /* */ 979 /* <Output> */ 980 /* sbit :: A handle to a small bitmap descriptor. */ 981 /* */ 982 /* anode :: Used to return the address of of the corresponding cache */ 983 /* node after incrementing its reference count (see note */ 984 /* below). */ 985 /* */ 986 /* <Return> */ 987 /* FreeType error code. 0~means success. */ 988 /* */ 989 /* <Note> */ 990 /* The small bitmap descriptor and its bit buffer are owned by the */ 991 /* cache and should never be freed by the application. They might */ 992 /* as well disappear from memory on the next cache lookup, so don't */ 993 /* treat them as persistent data. */ 994 /* */ 995 /* The descriptor's `buffer' field is set to~0 to indicate a missing */ 996 /* glyph bitmap. */ 997 /* */ 998 /* If `anode' is _not_ NULL, it receives the address of the cache */ 999 /* node containing the bitmap, after increasing its reference count. */ 1000 /* This ensures that the node (as well as the image) will always be */ 1001 /* kept in the cache until you call @FTC_Node_Unref to `release' it. */ 1002 /* */ 1003 /* If `anode' is NULL, the cache node is left unchanged, which means */ 1004 /* that the bitmap could be flushed out of the cache on the next */ 1005 /* call to one of the caching sub-system APIs. Don't assume that it */ 1006 /* is persistent! */ 1007 /* */ 1008 FT_EXPORT( FT_Error ) 1009 FTC_SBitCache_Lookup( FTC_SBitCache cache, 1010 FTC_ImageType type, 1011 FT_UInt gindex, 1012 FTC_SBit *sbit, 1013 FTC_Node *anode ); 1014 1015 1016 /*************************************************************************/ 1017 /* */ 1018 /* <Function> */ 1019 /* FTC_SBitCache_LookupScaler */ 1020 /* */ 1021 /* <Description> */ 1022 /* A variant of @FTC_SBitCache_Lookup that uses an @FTC_ScalerRec */ 1023 /* to specify the face ID and its size. */ 1024 /* */ 1025 /* <Input> */ 1026 /* cache :: A handle to the source sbit cache. */ 1027 /* */ 1028 /* scaler :: A pointer to the scaler descriptor. */ 1029 /* */ 1030 /* load_flags :: The corresponding load flags. */ 1031 /* */ 1032 /* gindex :: The glyph index. */ 1033 /* */ 1034 /* <Output> */ 1035 /* sbit :: A handle to a small bitmap descriptor. */ 1036 /* */ 1037 /* anode :: Used to return the address of of the corresponding */ 1038 /* cache node after incrementing its reference count */ 1039 /* (see note below). */ 1040 /* */ 1041 /* <Return> */ 1042 /* FreeType error code. 0~means success. */ 1043 /* */ 1044 /* <Note> */ 1045 /* The small bitmap descriptor and its bit buffer are owned by the */ 1046 /* cache and should never be freed by the application. They might */ 1047 /* as well disappear from memory on the next cache lookup, so don't */ 1048 /* treat them as persistent data. */ 1049 /* */ 1050 /* The descriptor's `buffer' field is set to~0 to indicate a missing */ 1051 /* glyph bitmap. */ 1052 /* */ 1053 /* If `anode' is _not_ NULL, it receives the address of the cache */ 1054 /* node containing the bitmap, after increasing its reference count. */ 1055 /* This ensures that the node (as well as the image) will always be */ 1056 /* kept in the cache until you call @FTC_Node_Unref to `release' it. */ 1057 /* */ 1058 /* If `anode' is NULL, the cache node is left unchanged, which means */ 1059 /* that the bitmap could be flushed out of the cache on the next */ 1060 /* call to one of the caching sub-system APIs. Don't assume that it */ 1061 /* is persistent! */ 1062 /* */ 1063 FT_EXPORT( FT_Error ) 1064 FTC_SBitCache_LookupScaler( FTC_SBitCache cache, 1065 FTC_Scaler scaler, 1066 FT_ULong load_flags, 1067 FT_UInt gindex, 1068 FTC_SBit *sbit, 1069 FTC_Node *anode ); 1070 1071 1072 /* */ 1073 1074 #ifdef FT_CONFIG_OPTION_OLD_INTERNALS 1075 1076 /*@***********************************************************************/ 1077 /* */ 1078 /* <Struct> */ 1079 /* FTC_FontRec */ 1080 /* */ 1081 /* <Description> */ 1082 /* A simple structure used to describe a given `font' to the cache */ 1083 /* manager. Note that a `font' is the combination of a given face */ 1084 /* with a given character size. */ 1085 /* */ 1086 /* <Fields> */ 1087 /* face_id :: The ID of the face to use. */ 1088 /* */ 1089 /* pix_width :: The character width in integer pixels. */ 1090 /* */ 1091 /* pix_height :: The character height in integer pixels. */ 1092 /* */ 1093 typedef struct FTC_FontRec_ 1094 { 1095 FTC_FaceID face_id; 1096 FT_UShort pix_width; 1097 FT_UShort pix_height; 1098 1099 } FTC_FontRec; 1100 1101 1102 /* */ 1103 1104 1105 #define FTC_FONT_COMPARE( f1, f2 ) \ 1106 ( (f1)->face_id == (f2)->face_id && \ 1107 (f1)->pix_width == (f2)->pix_width && \ 1108 (f1)->pix_height == (f2)->pix_height ) 1109 1110 /* this macro is incompatible with LLP64, should not be used */ 1111 #define FTC_FONT_HASH( f ) \ 1112 (FT_UInt32)( FTC_FACE_ID_HASH((f)->face_id) ^ \ 1113 ((f)->pix_width << 8) ^ \ 1114 ((f)->pix_height) ) 1115 1116 typedef FTC_FontRec* FTC_Font; 1117 1118 1119 FT_EXPORT( FT_Error ) 1120 FTC_Manager_Lookup_Face( FTC_Manager manager, 1121 FTC_FaceID face_id, 1122 FT_Face *aface ); 1123 1124 FT_EXPORT( FT_Error ) 1125 FTC_Manager_Lookup_Size( FTC_Manager manager, 1126 FTC_Font font, 1127 FT_Face *aface, 1128 FT_Size *asize ); 1129 1130 #endif /* FT_CONFIG_OPTION_OLD_INTERNALS */ 1131 1132 1133 /* */ 1134 1135 FT_END_HEADER 1136 1137 #endif /* __FTCACHE_H__ */ 1138 1139 1140 /* END */ 1141
