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