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