1/***************************************************************************/ 2/* */ 3/* ftcache.h */ 4/* */ 5/* FreeType Cache subsystem (specification). */ 6/* */ 7/* Copyright 1996-2008, 2010, 2013 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 27FT_BEGIN_HEADER 28 29 30 /************************************************************************* 31 * 32 * <Section> 33 * cache_subsystem 34 * 35 * <Title> 36 * Cache Sub-System 37 * 38 * <Abstract> 39 * How to cache face, size, and glyph data with FreeType~2. 40 * 41 * <Description> 42 * This section describes the FreeType~2 cache sub-system, which is used 43 * to limit the number of concurrently opened @FT_Face and @FT_Size 44 * objects, as well as caching information like character maps and glyph 45 * images while limiting their maximum memory usage. 46 * 47 * Note that all types and functions begin with the `FTC_' prefix. 48 * 49 * The cache is highly portable and thus doesn't know anything about the 50 * fonts installed on your system, or how to access them. This implies 51 * the following scheme: 52 * 53 * First, available or installed font faces are uniquely identified by 54 * @FTC_FaceID values, provided to the cache by the client. Note that 55 * the cache only stores and compares these values, and doesn't try to 56 * interpret them in any way. 57 * 58 * Second, the cache calls, only when needed, a client-provided function 59 * to convert an @FTC_FaceID into a new @FT_Face object. The latter is 60 * then completely managed by the cache, including its termination 61 * through @FT_Done_Face. To monitor termination of face objects, the 62 * finalizer callback in the `generic' field of the @FT_Face object can 63 * be used, which might also be used to store the @FTC_FaceID of the 64 * face. 65 * 66 * Clients are free to map face IDs to anything else. The most simple 67 * usage is to associate them to a (pathname,face_index) pair that is 68 * used to call @FT_New_Face. However, more complex schemes are also 69 * possible. 70 * 71 * Note that for the cache to work correctly, the face ID values must be 72 * *persistent*, which means that the contents they point to should not 73 * change at runtime, or that their value should not become invalid. 74 * 75 * If this is unavoidable (e.g., when a font is uninstalled at runtime), 76 * you should call @FTC_Manager_RemoveFaceID as soon as possible, to let 77 * the cache get rid of any references to the old @FTC_FaceID it may 78 * keep internally. Failure to do so will lead to incorrect behaviour 79 * or even crashes. 80 * 81 * To use the cache, start with calling @FTC_Manager_New to create a new 82 * @FTC_Manager object, which models a single cache instance. You can 83 * then look up @FT_Face and @FT_Size objects with 84 * @FTC_Manager_LookupFace and @FTC_Manager_LookupSize, respectively. 85 * 86 * If you want to use the charmap caching, call @FTC_CMapCache_New, then 87 * later use @FTC_CMapCache_Lookup to perform the equivalent of 88 * @FT_Get_Char_Index, only much faster. 89 * 90 * If you want to use the @FT_Glyph caching, call @FTC_ImageCache, then 91 * later use @FTC_ImageCache_Lookup to retrieve the corresponding 92 * @FT_Glyph objects from the cache. 93 * 94 * If you need lots of small bitmaps, it is much more memory efficient 95 * to call @FTC_SBitCache_New followed by @FTC_SBitCache_Lookup. This 96 * returns @FTC_SBitRec structures, which are used to store small 97 * bitmaps directly. (A small bitmap is one whose metrics and 98 * dimensions all fit into 8-bit integers). 99 * 100 * We hope to also provide a kerning cache in the near future. 101 * 102 * 103 * <Order> 104 * FTC_Manager 105 * FTC_FaceID 106 * FTC_Face_Requester 107 * 108 * FTC_Manager_New 109 * FTC_Manager_Reset 110 * FTC_Manager_Done 111 * FTC_Manager_LookupFace 112 * FTC_Manager_LookupSize 113 * FTC_Manager_RemoveFaceID 114 * 115 * FTC_Node 116 * FTC_Node_Unref 117 * 118 * FTC_ImageCache 119 * FTC_ImageCache_New 120 * FTC_ImageCache_Lookup 121 * 122 * FTC_SBit 123 * FTC_SBitCache 124 * FTC_SBitCache_New 125 * FTC_SBitCache_Lookup 126 * 127 * FTC_CMapCache 128 * FTC_CMapCache_New 129 * FTC_CMapCache_Lookup 130 * 131 *************************************************************************/ 132 133 134 /*************************************************************************/ 135 /*************************************************************************/ 136 /*************************************************************************/ 137 /***** *****/ 138 /***** BASIC TYPE DEFINITIONS *****/ 139 /***** *****/ 140 /*************************************************************************/ 141 /*************************************************************************/ 142 /*************************************************************************/ 143 144 145 /************************************************************************* 146 * 147 * @type: FTC_FaceID 148 * 149 * @description: 150 * An opaque pointer type that is used to identity face objects. The 151 * contents of such objects is application-dependent. 152 * 153 * These pointers are typically used to point to a user-defined 154 * structure containing a font file path, and face index. 155 * 156 * @note: 157 * Never use NULL as a valid @FTC_FaceID. 158 * 159 * Face IDs are passed by the client to the cache manager, which calls, 160 * when needed, the @FTC_Face_Requester to translate them into new 161 * @FT_Face objects. 162 * 163 * If the content of a given face ID changes at runtime, or if the value 164 * becomes invalid (e.g., when uninstalling a font), you should 165 * immediately call @FTC_Manager_RemoveFaceID before any other cache 166 * function. 167 * 168 * Failure to do so will result in incorrect behaviour or even 169 * memory leaks and crashes. 170 */ 171 typedef FT_Pointer FTC_FaceID; 172 173 174 /************************************************************************ 175 * 176 * @functype: 177 * FTC_Face_Requester 178 * 179 * @description: 180 * A callback function provided by client applications. It is used by 181 * the cache manager to translate a given @FTC_FaceID into a new valid 182 * @FT_Face object, on demand. 183 * 184 * <Input> 185 * face_id :: 186 * The face ID to resolve. 187 * 188 * library :: 189 * A handle to a FreeType library object. 190 * 191 * req_data :: 192 * Application-provided request data (see note below). 193 * 194 * <Output> 195 * aface :: 196 * A new @FT_Face handle. 197 * 198 * <Return> 199 * FreeType error code. 0~means success. 200 * 201 * <Note> 202 * The third parameter `req_data' is the same as the one passed by the 203 * client when @FTC_Manager_New is called. 204 * 205 * The face requester should not perform funny things on the returned 206 * face object, like creating a new @FT_Size for it, or setting a 207 * transformation through @FT_Set_Transform! 208 */ 209 typedef FT_Error 210 (*FTC_Face_Requester)( FTC_FaceID face_id, 211 FT_Library library, 212 FT_Pointer request_data, 213 FT_Face* aface ); 214 215 /* */ 216 217 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 /* <Section> */ 546 /* cache_subsystem */ 547 /* */ 548 /*************************************************************************/ 549 550 /************************************************************************* 551 * 552 * @type: 553 * FTC_CMapCache 554 * 555 * @description: 556 * An opaque handle used to model a charmap cache. This cache is to 557 * hold character codes -> glyph indices mappings. 558 * 559 */ 560 typedef struct FTC_CMapCacheRec_* FTC_CMapCache; 561 562 563 /************************************************************************* 564 * 565 * @function: 566 * FTC_CMapCache_New 567 * 568 * @description: 569 * Create a new charmap cache. 570 * 571 * @input: 572 * manager :: 573 * A handle to the cache manager. 574 * 575 * @output: 576 * acache :: 577 * A new cache handle. NULL in case of error. 578 * 579 * @return: 580 * FreeType error code. 0~means success. 581 * 582 * @note: 583 * Like all other caches, this one will be destroyed with the cache 584 * manager. 585 * 586 */ 587 FT_EXPORT( FT_Error ) 588 FTC_CMapCache_New( FTC_Manager manager, 589 FTC_CMapCache *acache ); 590 591 592 /************************************************************************ 593 * 594 * @function: 595 * FTC_CMapCache_Lookup 596 * 597 * @description: 598 * Translate a character code into a glyph index, using the charmap 599 * cache. 600 * 601 * @input: 602 * cache :: 603 * A charmap cache handle. 604 * 605 * face_id :: 606 * The source face ID. 607 * 608 * cmap_index :: 609 * The index of the charmap in the source face. Any negative value 610 * means to use the cache @FT_Face's default charmap. 611 * 612 * char_code :: 613 * The character code (in the corresponding charmap). 614 * 615 * @return: 616 * Glyph index. 0~means `no glyph'. 617 * 618 */ 619 FT_EXPORT( FT_UInt ) 620 FTC_CMapCache_Lookup( FTC_CMapCache cache, 621 FTC_FaceID face_id, 622 FT_Int cmap_index, 623 FT_UInt32 char_code ); 624 625 626 /*************************************************************************/ 627 /* */ 628 /* <Section> */ 629 /* cache_subsystem */ 630 /* */ 631 /*************************************************************************/ 632 633 634 /*************************************************************************/ 635 /*************************************************************************/ 636 /*************************************************************************/ 637 /***** *****/ 638 /***** IMAGE CACHE OBJECT *****/ 639 /***** *****/ 640 /*************************************************************************/ 641 /*************************************************************************/ 642 /*************************************************************************/ 643 644 645 /************************************************************************* 646 * 647 * @struct: 648 * FTC_ImageTypeRec 649 * 650 * @description: 651 * A structure used to model the type of images in a glyph cache. 652 * 653 * @fields: 654 * face_id :: 655 * The face ID. 656 * 657 * width :: 658 * The width in pixels. 659 * 660 * height :: 661 * The height in pixels. 662 * 663 * flags :: 664 * The load flags, as in @FT_Load_Glyph. 665 * 666 */ 667 typedef struct FTC_ImageTypeRec_ 668 { 669 FTC_FaceID face_id; 670 FT_Int width; 671 FT_Int height; 672 FT_Int32 flags; 673 674 } FTC_ImageTypeRec; 675 676 677 /************************************************************************* 678 * 679 * @type: 680 * FTC_ImageType 681 * 682 * @description: 683 * A handle to an @FTC_ImageTypeRec structure. 684 * 685 */ 686 typedef struct FTC_ImageTypeRec_* FTC_ImageType; 687 688 689 /* */ 690 691 692#define FTC_IMAGE_TYPE_COMPARE( d1, d2 ) \ 693 ( (d1)->face_id == (d2)->face_id && \ 694 (d1)->width == (d2)->width && \ 695 (d1)->flags == (d2)->flags ) 696 697 698 /*************************************************************************/ 699 /* */ 700 /* <Type> */ 701 /* FTC_ImageCache */ 702 /* */ 703 /* <Description> */ 704 /* A handle to a glyph image cache object. They are designed to */ 705 /* hold many distinct glyph images while not exceeding a certain */ 706 /* memory threshold. */ 707 /* */ 708 typedef struct FTC_ImageCacheRec_* FTC_ImageCache; 709 710 711 /*************************************************************************/ 712 /* */ 713 /* <Function> */ 714 /* FTC_ImageCache_New */ 715 /* */ 716 /* <Description> */ 717 /* Create a new glyph image cache. */ 718 /* */ 719 /* <Input> */ 720 /* manager :: The parent manager for the image cache. */ 721 /* */ 722 /* <Output> */ 723 /* acache :: A handle to the new glyph image cache object. */ 724 /* */ 725 /* <Return> */ 726 /* FreeType error code. 0~means success. */ 727 /* */ 728 FT_EXPORT( FT_Error ) 729 FTC_ImageCache_New( FTC_Manager manager, 730 FTC_ImageCache *acache ); 731 732 733 /*************************************************************************/ 734 /* */ 735 /* <Function> */ 736 /* FTC_ImageCache_Lookup */ 737 /* */ 738 /* <Description> */ 739 /* Retrieve a given glyph image from a glyph image cache. */ 740 /* */ 741 /* <Input> */ 742 /* cache :: A handle to the source glyph image cache. */ 743 /* */ 744 /* type :: A pointer to a glyph image type descriptor. */ 745 /* */ 746 /* gindex :: The glyph index to retrieve. */ 747 /* */ 748 /* <Output> */ 749 /* aglyph :: The corresponding @FT_Glyph object. 0~in case of */ 750 /* failure. */ 751 /* */ 752 /* anode :: Used to return the address of of the corresponding cache */ 753 /* node after incrementing its reference count (see note */ 754 /* below). */ 755 /* */ 756 /* <Return> */ 757 /* FreeType error code. 0~means success. */ 758 /* */ 759 /* <Note> */ 760 /* The returned glyph is owned and managed by the glyph image cache. */ 761 /* Never try to transform or discard it manually! You can however */ 762 /* create a copy with @FT_Glyph_Copy and modify the new one. */ 763 /* */ 764 /* If `anode' is _not_ NULL, it receives the address of the cache */ 765 /* node containing the glyph image, after increasing its reference */ 766 /* count. This ensures that the node (as well as the @FT_Glyph) will */ 767 /* always be kept in the cache until you call @FTC_Node_Unref to */ 768 /* `release' it. */ 769 /* */ 770 /* If `anode' is NULL, the cache node is left unchanged, which means */ 771 /* that the @FT_Glyph could be flushed out of the cache on the next */ 772 /* call to one of the caching sub-system APIs. Don't assume that it */ 773 /* is persistent! */ 774 /* */ 775 FT_EXPORT( FT_Error ) 776 FTC_ImageCache_Lookup( FTC_ImageCache cache, 777 FTC_ImageType type, 778 FT_UInt gindex, 779 FT_Glyph *aglyph, 780 FTC_Node *anode ); 781 782 783 /*************************************************************************/ 784 /* */ 785 /* <Function> */ 786 /* FTC_ImageCache_LookupScaler */ 787 /* */ 788 /* <Description> */ 789 /* A variant of @FTC_ImageCache_Lookup that uses an @FTC_ScalerRec */ 790 /* to specify the face ID and its size. */ 791 /* */ 792 /* <Input> */ 793 /* cache :: A handle to the source glyph image cache. */ 794 /* */ 795 /* scaler :: A pointer to a scaler descriptor. */ 796 /* */ 797 /* load_flags :: The corresponding load flags. */ 798 /* */ 799 /* gindex :: The glyph index to retrieve. */ 800 /* */ 801 /* <Output> */ 802 /* aglyph :: The corresponding @FT_Glyph object. 0~in case of */ 803 /* failure. */ 804 /* */ 805 /* anode :: Used to return the address of of the corresponding */ 806 /* cache node after incrementing its reference count */ 807 /* (see note below). */ 808 /* */ 809 /* <Return> */ 810 /* FreeType error code. 0~means success. */ 811 /* */ 812 /* <Note> */ 813 /* The returned glyph is owned and managed by the glyph image cache. */ 814 /* Never try to transform or discard it manually! You can however */ 815 /* create a copy with @FT_Glyph_Copy and modify the new one. */ 816 /* */ 817 /* If `anode' is _not_ NULL, it receives the address of the cache */ 818 /* node containing the glyph image, after increasing its reference */ 819 /* count. This ensures that the node (as well as the @FT_Glyph) will */ 820 /* always be kept in the cache until you call @FTC_Node_Unref to */ 821 /* `release' it. */ 822 /* */ 823 /* If `anode' is NULL, the cache node is left unchanged, which means */ 824 /* that the @FT_Glyph could be flushed out of the cache on the next */ 825 /* call to one of the caching sub-system APIs. Don't assume that it */ 826 /* is persistent! */ 827 /* */ 828 /* Calls to @FT_Set_Char_Size and friends have no effect on cached */ 829 /* glyphs; you should always use the FreeType cache API instead. */ 830 /* */ 831 FT_EXPORT( FT_Error ) 832 FTC_ImageCache_LookupScaler( FTC_ImageCache cache, 833 FTC_Scaler scaler, 834 FT_ULong load_flags, 835 FT_UInt gindex, 836 FT_Glyph *aglyph, 837 FTC_Node *anode ); 838 839 840 /*************************************************************************/ 841 /* */ 842 /* <Type> */ 843 /* FTC_SBit */ 844 /* */ 845 /* <Description> */ 846 /* A handle to a small bitmap descriptor. See the @FTC_SBitRec */ 847 /* structure for details. */ 848 /* */ 849 typedef struct FTC_SBitRec_* FTC_SBit; 850 851 852 /*************************************************************************/ 853 /* */ 854 /* <Struct> */ 855 /* FTC_SBitRec */ 856 /* */ 857 /* <Description> */ 858 /* A very compact structure used to describe a small glyph bitmap. */ 859 /* */ 860 /* <Fields> */ 861 /* width :: The bitmap width in pixels. */ 862 /* */ 863 /* height :: The bitmap height in pixels. */ 864 /* */ 865 /* left :: The horizontal distance from the pen position to the */ 866 /* left bitmap border (a.k.a. `left side bearing', or */ 867 /* `lsb'). */ 868 /* */ 869 /* top :: The vertical distance from the pen position (on the */ 870 /* baseline) to the upper bitmap border (a.k.a. `top */ 871 /* side bearing'). The distance is positive for upwards */ 872 /* y~coordinates. */ 873 /* */ 874 /* format :: The format of the glyph bitmap (monochrome or gray). */ 875 /* */ 876 /* max_grays :: Maximum gray level value (in the range 1 to~255). */ 877 /* */ 878 /* pitch :: The number of bytes per bitmap line. May be positive */ 879 /* or negative. */ 880 /* */ 881 /* xadvance :: The horizontal advance width in pixels. */ 882 /* */ 883 /* yadvance :: The vertical advance height in pixels. */ 884 /* */ 885 /* buffer :: A pointer to the bitmap pixels. */ 886 /* */ 887 typedef struct FTC_SBitRec_ 888 { 889 FT_Byte width; 890 FT_Byte height; 891 FT_Char left; 892 FT_Char top; 893 894 FT_Byte format; 895 FT_Byte max_grays; 896 FT_Short pitch; 897 FT_Char xadvance; 898 FT_Char yadvance; 899 900 FT_Byte* buffer; 901 902 } FTC_SBitRec; 903 904 905 /*************************************************************************/ 906 /* */ 907 /* <Type> */ 908 /* FTC_SBitCache */ 909 /* */ 910 /* <Description> */ 911 /* A handle to a small bitmap cache. These are special cache objects */ 912 /* used to store small glyph bitmaps (and anti-aliased pixmaps) in a */ 913 /* much more efficient way than the traditional glyph image cache */ 914 /* implemented by @FTC_ImageCache. */ 915 /* */ 916 typedef struct FTC_SBitCacheRec_* FTC_SBitCache; 917 918 919 /*************************************************************************/ 920 /* */ 921 /* <Function> */ 922 /* FTC_SBitCache_New */ 923 /* */ 924 /* <Description> */ 925 /* Create a new cache to store small glyph bitmaps. */ 926 /* */ 927 /* <Input> */ 928 /* manager :: A handle to the source cache manager. */ 929 /* */ 930 /* <Output> */ 931 /* acache :: A handle to the new sbit cache. NULL in case of error. */ 932 /* */ 933 /* <Return> */ 934 /* FreeType error code. 0~means success. */ 935 /* */ 936 FT_EXPORT( FT_Error ) 937 FTC_SBitCache_New( FTC_Manager manager, 938 FTC_SBitCache *acache ); 939 940 941 /*************************************************************************/ 942 /* */ 943 /* <Function> */ 944 /* FTC_SBitCache_Lookup */ 945 /* */ 946 /* <Description> */ 947 /* Look up a given small glyph bitmap in a given sbit cache and */ 948 /* `lock' it to prevent its flushing from the cache until needed. */ 949 /* */ 950 /* <Input> */ 951 /* cache :: A handle to the source sbit cache. */ 952 /* */ 953 /* type :: A pointer to the glyph image type descriptor. */ 954 /* */ 955 /* gindex :: The glyph index. */ 956 /* */ 957 /* <Output> */ 958 /* sbit :: A handle to a small bitmap descriptor. */ 959 /* */ 960 /* anode :: Used to return the address of of the corresponding cache */ 961 /* node after incrementing its reference count (see note */ 962 /* below). */ 963 /* */ 964 /* <Return> */ 965 /* FreeType error code. 0~means success. */ 966 /* */ 967 /* <Note> */ 968 /* The small bitmap descriptor and its bit buffer are owned by the */ 969 /* cache and should never be freed by the application. They might */ 970 /* as well disappear from memory on the next cache lookup, so don't */ 971 /* treat them as persistent data. */ 972 /* */ 973 /* The descriptor's `buffer' field is set to~0 to indicate a missing */ 974 /* glyph bitmap. */ 975 /* */ 976 /* If `anode' is _not_ NULL, it receives the address of the cache */ 977 /* node containing the bitmap, after increasing its reference count. */ 978 /* This ensures that the node (as well as the image) will always be */ 979 /* kept in the cache until you call @FTC_Node_Unref to `release' it. */ 980 /* */ 981 /* If `anode' is NULL, the cache node is left unchanged, which means */ 982 /* that the bitmap could be flushed out of the cache on the next */ 983 /* call to one of the caching sub-system APIs. Don't assume that it */ 984 /* is persistent! */ 985 /* */ 986 FT_EXPORT( FT_Error ) 987 FTC_SBitCache_Lookup( FTC_SBitCache cache, 988 FTC_ImageType type, 989 FT_UInt gindex, 990 FTC_SBit *sbit, 991 FTC_Node *anode ); 992 993 994 /*************************************************************************/ 995 /* */ 996 /* <Function> */ 997 /* FTC_SBitCache_LookupScaler */ 998 /* */ 999 /* <Description> */ 1000 /* A variant of @FTC_SBitCache_Lookup that uses an @FTC_ScalerRec */ 1001 /* to specify the face ID and its size. */ 1002 /* */ 1003 /* <Input> */ 1004 /* cache :: A handle to the source sbit cache. */ 1005 /* */ 1006 /* scaler :: A pointer to the scaler descriptor. */ 1007 /* */ 1008 /* load_flags :: The corresponding load flags. */ 1009 /* */ 1010 /* gindex :: The glyph index. */ 1011 /* */ 1012 /* <Output> */ 1013 /* sbit :: A handle to a small bitmap descriptor. */ 1014 /* */ 1015 /* anode :: Used to return the address of of the corresponding */ 1016 /* cache node after incrementing its reference count */ 1017 /* (see note below). */ 1018 /* */ 1019 /* <Return> */ 1020 /* FreeType error code. 0~means success. */ 1021 /* */ 1022 /* <Note> */ 1023 /* The small bitmap descriptor and its bit buffer are owned by the */ 1024 /* cache and should never be freed by the application. They might */ 1025 /* as well disappear from memory on the next cache lookup, so don't */ 1026 /* treat them as persistent data. */ 1027 /* */ 1028 /* The descriptor's `buffer' field is set to~0 to indicate a missing */ 1029 /* glyph bitmap. */ 1030 /* */ 1031 /* If `anode' is _not_ NULL, it receives the address of the cache */ 1032 /* node containing the bitmap, after increasing its reference count. */ 1033 /* This ensures that the node (as well as the image) will always be */ 1034 /* kept in the cache until you call @FTC_Node_Unref to `release' it. */ 1035 /* */ 1036 /* If `anode' is NULL, the cache node is left unchanged, which means */ 1037 /* that the bitmap could be flushed out of the cache on the next */ 1038 /* call to one of the caching sub-system APIs. Don't assume that it */ 1039 /* is persistent! */ 1040 /* */ 1041 FT_EXPORT( FT_Error ) 1042 FTC_SBitCache_LookupScaler( FTC_SBitCache cache, 1043 FTC_Scaler scaler, 1044 FT_ULong load_flags, 1045 FT_UInt gindex, 1046 FTC_SBit *sbit, 1047 FTC_Node *anode ); 1048 1049 1050 /* */ 1051 1052FT_END_HEADER 1053 1054#endif /* __FTCACHE_H__ */ 1055 1056 1057/* END */ 1058