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