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