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