00001 /***************************************************************************/ 00002 /* */ 00003 /* ftcache.h */ 00004 /* */ 00005 /* FreeType Cache subsystem (specification). */ 00006 /* */ 00007 /* Copyright 1996-2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 by */ 00008 /* David Turner, Robert Wilhelm, and Werner Lemberg. */ 00009 /* */ 00010 /* This file is part of the FreeType project, and may only be used, */ 00011 /* modified, and distributed under the terms of the FreeType project */ 00012 /* license, LICENSE.TXT. By continuing to use, modify, or distribute */ 00013 /* this file you indicate that you have read the license and */ 00014 /* understand and accept it fully. */ 00015 /* */ 00016 /***************************************************************************/ 00017 00018 00019 #ifndef __FTCACHE_H__ 00020 #define __FTCACHE_H__ 00021 00022 00023 #include <ft2build.h> 00024 #include FT_GLYPH_H 00025 00026 00027 FT_BEGIN_HEADER 00028 00029 00030 /************************************************************************* 00031 * 00032 * <Section> 00033 * cache_subsystem 00034 * 00035 * <Title> 00036 * Cache Sub-System 00037 * 00038 * <Abstract> 00039 * How to cache face, size, and glyph data with FreeType~2. 00040 * 00041 * <Description> 00042 * This section describes the FreeType~2 cache sub-system, which is used 00043 * to limit the number of concurrently opened @FT_Face and @FT_Size 00044 * objects, as well as caching information like character maps and glyph 00045 * images while limiting their maximum memory usage. 00046 * 00047 * Note that all types and functions begin with the `FTC_' prefix. 00048 * 00049 * The cache is highly portable and thus doesn't know anything about the 00050 * fonts installed on your system, or how to access them. This implies 00051 * the following scheme: 00052 * 00053 * First, available or installed font faces are uniquely identified by 00054 * @FTC_FaceID values, provided to the cache by the client. Note that 00055 * the cache only stores and compares these values, and doesn't try to 00056 * interpret them in any way. 00057 * 00058 * Second, the cache calls, only when needed, a client-provided function 00059 * to convert a @FTC_FaceID into a new @FT_Face object. The latter is 00060 * then completely managed by the cache, including its termination 00061 * through @FT_Done_Face. 00062 * 00063 * Clients are free to map face IDs to anything else. The most simple 00064 * usage is to associate them to a (pathname,face_index) pair that is 00065 * used to call @FT_New_Face. However, more complex schemes are also 00066 * possible. 00067 * 00068 * Note that for the cache to work correctly, the face ID values must be 00069 * *persistent*, which means that the contents they point to should not 00070 * change at runtime, or that their value should not become invalid. 00071 * 00072 * If this is unavoidable (e.g., when a font is uninstalled at runtime), 00073 * you should call @FTC_Manager_RemoveFaceID as soon as possible, to let 00074 * the cache get rid of any references to the old @FTC_FaceID it may 00075 * keep internally. Failure to do so will lead to incorrect behaviour 00076 * or even crashes. 00077 * 00078 * To use the cache, start with calling @FTC_Manager_New to create a new 00079 * @FTC_Manager object, which models a single cache instance. You can 00080 * then look up @FT_Face and @FT_Size objects with 00081 * @FTC_Manager_LookupFace and @FTC_Manager_LookupSize, respectively. 00082 * 00083 * If you want to use the charmap caching, call @FTC_CMapCache_New, then 00084 * later use @FTC_CMapCache_Lookup to perform the equivalent of 00085 * @FT_Get_Char_Index, only much faster. 00086 * 00087 * If you want to use the @FT_Glyph caching, call @FTC_ImageCache, then 00088 * later use @FTC_ImageCache_Lookup to retrieve the corresponding 00089 * @FT_Glyph objects from the cache. 00090 * 00091 * If you need lots of small bitmaps, it is much more memory efficient 00092 * to call @FTC_SBitCache_New followed by @FTC_SBitCache_Lookup. This 00093 * returns @FTC_SBitRec structures, which are used to store small 00094 * bitmaps directly. (A small bitmap is one whose metrics and 00095 * dimensions all fit into 8-bit integers). 00096 * 00097 * We hope to also provide a kerning cache in the near future. 00098 * 00099 * 00100 * <Order> 00101 * FTC_Manager 00102 * FTC_FaceID 00103 * FTC_Face_Requester 00104 * 00105 * FTC_Manager_New 00106 * FTC_Manager_Reset 00107 * FTC_Manager_Done 00108 * FTC_Manager_LookupFace 00109 * FTC_Manager_LookupSize 00110 * FTC_Manager_RemoveFaceID 00111 * 00112 * FTC_Node 00113 * FTC_Node_Unref 00114 * 00115 * FTC_ImageCache 00116 * FTC_ImageCache_New 00117 * FTC_ImageCache_Lookup 00118 * 00119 * FTC_SBit 00120 * FTC_SBitCache 00121 * FTC_SBitCache_New 00122 * FTC_SBitCache_Lookup 00123 * 00124 * FTC_CMapCache 00125 * FTC_CMapCache_New 00126 * FTC_CMapCache_Lookup 00127 * 00128 *************************************************************************/ 00129 00130 00131 /*************************************************************************/ 00132 /*************************************************************************/ 00133 /*************************************************************************/ 00134 /***** *****/ 00135 /***** BASIC TYPE DEFINITIONS *****/ 00136 /***** *****/ 00137 /*************************************************************************/ 00138 /*************************************************************************/ 00139 /*************************************************************************/ 00140 00141 00142 /************************************************************************* 00143 * 00144 * @type: FTC_FaceID 00145 * 00146 * @description: 00147 * An opaque pointer type that is used to identity face objects. The 00148 * contents of such objects is application-dependent. 00149 * 00150 * These pointers are typically used to point to a user-defined 00151 * structure containing a font file path, and face index. 00152 * 00153 * @note: 00154 * Never use NULL as a valid @FTC_FaceID. 00155 * 00156 * Face IDs are passed by the client to the cache manager, which calls, 00157 * when needed, the @FTC_Face_Requester to translate them into new 00158 * @FT_Face objects. 00159 * 00160 * If the content of a given face ID changes at runtime, or if the value 00161 * becomes invalid (e.g., when uninstalling a font), you should 00162 * immediately call @FTC_Manager_RemoveFaceID before any other cache 00163 * function. 00164 * 00165 * Failure to do so will result in incorrect behaviour or even 00166 * memory leaks and crashes. 00167 */ 00168 typedef FT_Pointer FTC_FaceID; 00169 00170 00171 /************************************************************************ 00172 * 00173 * @functype: 00174 * FTC_Face_Requester 00175 * 00176 * @description: 00177 * A callback function provided by client applications. It is used by 00178 * the cache manager to translate a given @FTC_FaceID into a new valid 00179 * @FT_Face object, on demand. 00180 * 00181 * <Input> 00182 * face_id :: 00183 * The face ID to resolve. 00184 * 00185 * library :: 00186 * A handle to a FreeType library object. 00187 * 00188 * req_data :: 00189 * Application-provided request data (see note below). 00190 * 00191 * <Output> 00192 * aface :: 00193 * A new @FT_Face handle. 00194 * 00195 * <Return> 00196 * FreeType error code. 0~means success. 00197 * 00198 * <Note> 00199 * The third parameter `req_data' is the same as the one passed by the 00200 * client when @FTC_Manager_New is called. 00201 * 00202 * The face requester should not perform funny things on the returned 00203 * face object, like creating a new @FT_Size for it, or setting a 00204 * transformation through @FT_Set_Transform! 00205 */ 00206 typedef FT_Error 00207 (*FTC_Face_Requester)( FTC_FaceID face_id, 00208 FT_Library library, 00209 FT_Pointer request_data, 00210 FT_Face* aface ); 00211 00212 /* */ 00213 00214 #define FT_POINTER_TO_ULONG( p ) ( (FT_ULong)(FT_Pointer)(p) ) 00215 00216 #define FTC_FACE_ID_HASH( i ) \ 00217 ((FT_UInt32)(( FT_POINTER_TO_ULONG( i ) >> 3 ) ^ \ 00218 ( FT_POINTER_TO_ULONG( i ) << 7 ) ) ) 00219 00220 00221 /*************************************************************************/ 00222 /*************************************************************************/ 00223 /*************************************************************************/ 00224 /***** *****/ 00225 /***** CACHE MANAGER OBJECT *****/ 00226 /***** *****/ 00227 /*************************************************************************/ 00228 /*************************************************************************/ 00229 /*************************************************************************/ 00230 00231 00232 /*************************************************************************/ 00233 /* */ 00234 /* <Type> */ 00235 /* FTC_Manager */ 00236 /* */ 00237 /* <Description> */ 00238 /* This object corresponds to one instance of the cache-subsystem. */ 00239 /* It is used to cache one or more @FT_Face objects, along with */ 00240 /* corresponding @FT_Size objects. */ 00241 /* */ 00242 /* The manager intentionally limits the total number of opened */ 00243 /* @FT_Face and @FT_Size objects to control memory usage. See the */ 00244 /* `max_faces' and `max_sizes' parameters of @FTC_Manager_New. */ 00245 /* */ 00246 /* The manager is also used to cache `nodes' of various types while */ 00247 /* limiting their total memory usage. */ 00248 /* */ 00249 /* All limitations are enforced by keeping lists of managed objects */ 00250 /* in most-recently-used order, and flushing old nodes to make room */ 00251 /* for new ones. */ 00252 /* */ 00253 typedef struct FTC_ManagerRec_* FTC_Manager; 00254 00255 00256 /*************************************************************************/ 00257 /* */ 00258 /* <Type> */ 00259 /* FTC_Node */ 00260 /* */ 00261 /* <Description> */ 00262 /* An opaque handle to a cache node object. Each cache node is */ 00263 /* reference-counted. A node with a count of~0 might be flushed */ 00264 /* out of a full cache whenever a lookup request is performed. */ 00265 /* */ 00266 /* If you lookup nodes, you have the ability to `acquire' them, i.e., */ 00267 /* to increment their reference count. This will prevent the node */ 00268 /* from being flushed out of the cache until you explicitly `release' */ 00269 /* it (see @FTC_Node_Unref). */ 00270 /* */ 00271 /* See also @FTC_SBitCache_Lookup and @FTC_ImageCache_Lookup. */ 00272 /* */ 00273 typedef struct FTC_NodeRec_* FTC_Node; 00274 00275 00276 /*************************************************************************/ 00277 /* */ 00278 /* <Function> */ 00279 /* FTC_Manager_New */ 00280 /* */ 00281 /* <Description> */ 00282 /* Create a new cache manager. */ 00283 /* */ 00284 /* <Input> */ 00285 /* library :: The parent FreeType library handle to use. */ 00286 /* */ 00287 /* max_faces :: Maximum number of opened @FT_Face objects managed by */ 00288 /* this cache instance. Use~0 for defaults. */ 00289 /* */ 00290 /* max_sizes :: Maximum number of opened @FT_Size objects managed by */ 00291 /* this cache instance. Use~0 for defaults. */ 00292 /* */ 00293 /* max_bytes :: Maximum number of bytes to use for cached data nodes. */ 00294 /* Use~0 for defaults. Note that this value does not */ 00295 /* account for managed @FT_Face and @FT_Size objects. */ 00296 /* */ 00297 /* requester :: An application-provided callback used to translate */ 00298 /* face IDs into real @FT_Face objects. */ 00299 /* */ 00300 /* req_data :: A generic pointer that is passed to the requester */ 00301 /* each time it is called (see @FTC_Face_Requester). */ 00302 /* */ 00303 /* <Output> */ 00304 /* amanager :: A handle to a new manager object. 0~in case of */ 00305 /* failure. */ 00306 /* */ 00307 /* <Return> */ 00308 /* FreeType error code. 0~means success. */ 00309 /* */ 00310 FT_EXPORT( FT_Error ) 00311 FTC_Manager_New( FT_Library library, 00312 FT_UInt max_faces, 00313 FT_UInt max_sizes, 00314 FT_ULong max_bytes, 00315 FTC_Face_Requester requester, 00316 FT_Pointer req_data, 00317 FTC_Manager *amanager ); 00318 00319 00320 /*************************************************************************/ 00321 /* */ 00322 /* <Function> */ 00323 /* FTC_Manager_Reset */ 00324 /* */ 00325 /* <Description> */ 00326 /* Empty a given cache manager. This simply gets rid of all the */ 00327 /* currently cached @FT_Face and @FT_Size objects within the manager. */ 00328 /* */ 00329 /* <InOut> */ 00330 /* manager :: A handle to the manager. */ 00331 /* */ 00332 FT_EXPORT( void ) 00333 FTC_Manager_Reset( FTC_Manager manager ); 00334 00335 00336 /*************************************************************************/ 00337 /* */ 00338 /* <Function> */ 00339 /* FTC_Manager_Done */ 00340 /* */ 00341 /* <Description> */ 00342 /* Destroy a given manager after emptying it. */ 00343 /* */ 00344 /* <Input> */ 00345 /* manager :: A handle to the target cache manager object. */ 00346 /* */ 00347 FT_EXPORT( void ) 00348 FTC_Manager_Done( FTC_Manager manager ); 00349 00350 00351 /*************************************************************************/ 00352 /* */ 00353 /* <Function> */ 00354 /* FTC_Manager_LookupFace */ 00355 /* */ 00356 /* <Description> */ 00357 /* Retrieve the @FT_Face object that corresponds to a given face ID */ 00358 /* through a cache manager. */ 00359 /* */ 00360 /* <Input> */ 00361 /* manager :: A handle to the cache manager. */ 00362 /* */ 00363 /* face_id :: The ID of the face object. */ 00364 /* */ 00365 /* <Output> */ 00366 /* aface :: A handle to the face object. */ 00367 /* */ 00368 /* <Return> */ 00369 /* FreeType error code. 0~means success. */ 00370 /* */ 00371 /* <Note> */ 00372 /* The returned @FT_Face object is always owned by the manager. You */ 00373 /* should never try to discard it yourself. */ 00374 /* */ 00375 /* The @FT_Face object doesn't necessarily have a current size object */ 00376 /* (i.e., face->size can be 0). If you need a specific `font size', */ 00377 /* use @FTC_Manager_LookupSize instead. */ 00378 /* */ 00379 /* Never change the face's transformation matrix (i.e., never call */ 00380 /* the @FT_Set_Transform function) on a returned face! If you need */ 00381 /* to transform glyphs, do it yourself after glyph loading. */ 00382 /* */ 00383 /* When you perform a lookup, out-of-memory errors are detected */ 00384 /* _within_ the lookup and force incremental flushes of the cache */ 00385 /* until enough memory is released for the lookup to succeed. */ 00386 /* */ 00387 /* If a lookup fails with `FT_Err_Out_Of_Memory' the cache has */ 00388 /* already been completely flushed, and still no memory was available */ 00389 /* for the operation. */ 00390 /* */ 00391 FT_EXPORT( FT_Error ) 00392 FTC_Manager_LookupFace( FTC_Manager manager, 00393 FTC_FaceID face_id, 00394 FT_Face *aface ); 00395 00396 00397 /*************************************************************************/ 00398 /* */ 00399 /* <Struct> */ 00400 /* FTC_ScalerRec */ 00401 /* */ 00402 /* <Description> */ 00403 /* A structure used to describe a given character size in either */ 00404 /* pixels or points to the cache manager. See */ 00405 /* @FTC_Manager_LookupSize. */ 00406 /* */ 00407 /* <Fields> */ 00408 /* face_id :: The source face ID. */ 00409 /* */ 00410 /* width :: The character width. */ 00411 /* */ 00412 /* height :: The character height. */ 00413 /* */ 00414 /* pixel :: A Boolean. If 1, the `width' and `height' fields are */ 00415 /* interpreted as integer pixel character sizes. */ 00416 /* Otherwise, they are expressed as 1/64th of points. */ 00417 /* */ 00418 /* x_res :: Only used when `pixel' is value~0 to indicate the */ 00419 /* horizontal resolution in dpi. */ 00420 /* */ 00421 /* y_res :: Only used when `pixel' is value~0 to indicate the */ 00422 /* vertical resolution in dpi. */ 00423 /* */ 00424 /* <Note> */ 00425 /* This type is mainly used to retrieve @FT_Size objects through the */ 00426 /* cache manager. */ 00427 /* */ 00428 typedef struct FTC_ScalerRec_ 00429 { 00430 FTC_FaceID face_id; 00431 FT_UInt width; 00432 FT_UInt height; 00433 FT_Int pixel; 00434 FT_UInt x_res; 00435 FT_UInt y_res; 00436 00437 } FTC_ScalerRec; 00438 00439 00440 /*************************************************************************/ 00441 /* */ 00442 /* <Struct> */ 00443 /* FTC_Scaler */ 00444 /* */ 00445 /* <Description> */ 00446 /* A handle to an @FTC_ScalerRec structure. */ 00447 /* */ 00448 typedef struct FTC_ScalerRec_* FTC_Scaler; 00449 00450 00451 /*************************************************************************/ 00452 /* */ 00453 /* <Function> */ 00454 /* FTC_Manager_LookupSize */ 00455 /* */ 00456 /* <Description> */ 00457 /* Retrieve the @FT_Size object that corresponds to a given */ 00458 /* @FTC_ScalerRec pointer through a cache manager. */ 00459 /* */ 00460 /* <Input> */ 00461 /* manager :: A handle to the cache manager. */ 00462 /* */ 00463 /* scaler :: A scaler handle. */ 00464 /* */ 00465 /* <Output> */ 00466 /* asize :: A handle to the size object. */ 00467 /* */ 00468 /* <Return> */ 00469 /* FreeType error code. 0~means success. */ 00470 /* */ 00471 /* <Note> */ 00472 /* The returned @FT_Size object is always owned by the manager. You */ 00473 /* should never try to discard it by yourself. */ 00474 /* */ 00475 /* You can access the parent @FT_Face object simply as `size->face' */ 00476 /* if you need it. Note that this object is also owned by the */ 00477 /* manager. */ 00478 /* */ 00479 /* <Note> */ 00480 /* When you perform a lookup, out-of-memory errors are detected */ 00481 /* _within_ the lookup and force incremental flushes of the cache */ 00482 /* until enough memory is released for the lookup to succeed. */ 00483 /* */ 00484 /* If a lookup fails with `FT_Err_Out_Of_Memory' the cache has */ 00485 /* already been completely flushed, and still no memory is available */ 00486 /* for the operation. */ 00487 /* */ 00488 FT_EXPORT( FT_Error ) 00489 FTC_Manager_LookupSize( FTC_Manager manager, 00490 FTC_Scaler scaler, 00491 FT_Size *asize ); 00492 00493 00494 /*************************************************************************/ 00495 /* */ 00496 /* <Function> */ 00497 /* FTC_Node_Unref */ 00498 /* */ 00499 /* <Description> */ 00500 /* Decrement a cache node's internal reference count. When the count */ 00501 /* reaches 0, it is not destroyed but becomes eligible for subsequent */ 00502 /* cache flushes. */ 00503 /* */ 00504 /* <Input> */ 00505 /* node :: The cache node handle. */ 00506 /* */ 00507 /* manager :: The cache manager handle. */ 00508 /* */ 00509 FT_EXPORT( void ) 00510 FTC_Node_Unref( FTC_Node node, 00511 FTC_Manager manager ); 00512 00513 00514 /************************************************************************* 00515 * 00516 * @function: 00517 * FTC_Manager_RemoveFaceID 00518 * 00519 * @description: 00520 * A special function used to indicate to the cache manager that 00521 * a given @FTC_FaceID is no longer valid, either because its 00522 * content changed, or because it was deallocated or uninstalled. 00523 * 00524 * @input: 00525 * manager :: 00526 * The cache manager handle. 00527 * 00528 * face_id :: 00529 * The @FTC_FaceID to be removed. 00530 * 00531 * @note: 00532 * This function flushes all nodes from the cache corresponding to this 00533 * `face_id', with the exception of nodes with a non-null reference 00534 * count. 00535 * 00536 * Such nodes are however modified internally so as to never appear 00537 * in later lookups with the same `face_id' value, and to be immediately 00538 * destroyed when released by all their users. 00539 * 00540 */ 00541 FT_EXPORT( void ) 00542 FTC_Manager_RemoveFaceID( FTC_Manager manager, 00543 FTC_FaceID face_id ); 00544 00545 00546 /*************************************************************************/ 00547 /* */ 00548 /* <Section> */ 00549 /* cache_subsystem */ 00550 /* */ 00551 /*************************************************************************/ 00552 00553 /************************************************************************* 00554 * 00555 * @type: 00556 * FTC_CMapCache 00557 * 00558 * @description: 00559 * An opaque handle used to model a charmap cache. This cache is to 00560 * hold character codes -> glyph indices mappings. 00561 * 00562 */ 00563 typedef struct FTC_CMapCacheRec_* FTC_CMapCache; 00564 00565 00566 /************************************************************************* 00567 * 00568 * @function: 00569 * FTC_CMapCache_New 00570 * 00571 * @description: 00572 * Create a new charmap cache. 00573 * 00574 * @input: 00575 * manager :: 00576 * A handle to the cache manager. 00577 * 00578 * @output: 00579 * acache :: 00580 * A new cache handle. NULL in case of error. 00581 * 00582 * @return: 00583 * FreeType error code. 0~means success. 00584 * 00585 * @note: 00586 * Like all other caches, this one will be destroyed with the cache 00587 * manager. 00588 * 00589 */ 00590 FT_EXPORT( FT_Error ) 00591 FTC_CMapCache_New( FTC_Manager manager, 00592 FTC_CMapCache *acache ); 00593 00594 00595 /************************************************************************ 00596 * 00597 * @function: 00598 * FTC_CMapCache_Lookup 00599 * 00600 * @description: 00601 * Translate a character code into a glyph index, using the charmap 00602 * cache. 00603 * 00604 * @input: 00605 * cache :: 00606 * A charmap cache handle. 00607 * 00608 * face_id :: 00609 * The source face ID. 00610 * 00611 * cmap_index :: 00612 * The index of the charmap in the source face. Any negative value 00613 * means to use the cache @FT_Face's default charmap. 00614 * 00615 * char_code :: 00616 * The character code (in the corresponding charmap). 00617 * 00618 * @return: 00619 * Glyph index. 0~means `no glyph'. 00620 * 00621 */ 00622 FT_EXPORT( FT_UInt ) 00623 FTC_CMapCache_Lookup( FTC_CMapCache cache, 00624 FTC_FaceID face_id, 00625 FT_Int cmap_index, 00626 FT_UInt32 char_code ); 00627 00628 00629 /*************************************************************************/ 00630 /* */ 00631 /* <Section> */ 00632 /* cache_subsystem */ 00633 /* */ 00634 /*************************************************************************/ 00635 00636 00637 /*************************************************************************/ 00638 /*************************************************************************/ 00639 /*************************************************************************/ 00640 /***** *****/ 00641 /***** IMAGE CACHE OBJECT *****/ 00642 /***** *****/ 00643 /*************************************************************************/ 00644 /*************************************************************************/ 00645 /*************************************************************************/ 00646 00647 00648 /************************************************************************* 00649 * 00650 * @struct: 00651 * FTC_ImageTypeRec 00652 * 00653 * @description: 00654 * A structure used to model the type of images in a glyph cache. 00655 * 00656 * @fields: 00657 * face_id :: 00658 * The face ID. 00659 * 00660 * width :: 00661 * The width in pixels. 00662 * 00663 * height :: 00664 * The height in pixels. 00665 * 00666 * flags :: 00667 * The load flags, as in @FT_Load_Glyph. 00668 * 00669 */ 00670 typedef struct FTC_ImageTypeRec_ 00671 { 00672 FTC_FaceID face_id; 00673 FT_Int width; 00674 FT_Int height; 00675 FT_Int32 flags; 00676 00677 } FTC_ImageTypeRec; 00678 00679 00680 /************************************************************************* 00681 * 00682 * @type: 00683 * FTC_ImageType 00684 * 00685 * @description: 00686 * A handle to an @FTC_ImageTypeRec structure. 00687 * 00688 */ 00689 typedef struct FTC_ImageTypeRec_* FTC_ImageType; 00690 00691 00692 /* */ 00693 00694 00695 #define FTC_IMAGE_TYPE_COMPARE( d1, d2 ) \ 00696 ( (d1)->face_id == (d2)->face_id && \ 00697 (d1)->width == (d2)->width && \ 00698 (d1)->flags == (d2)->flags ) 00699 00700 #define FTC_IMAGE_TYPE_HASH( d ) \ 00701 (FT_UFast)( FTC_FACE_ID_HASH( (d)->face_id ) ^ \ 00702 ( (d)->width << 8 ) ^ (d)->height ^ \ 00703 ( (d)->flags << 4 ) ) 00704 00705 00706 /*************************************************************************/ 00707 /* */ 00708 /* <Type> */ 00709 /* FTC_ImageCache */ 00710 /* */ 00711 /* <Description> */ 00712 /* A handle to an glyph image cache object. They are designed to */ 00713 /* hold many distinct glyph images while not exceeding a certain */ 00714 /* memory threshold. */ 00715 /* */ 00716 typedef struct FTC_ImageCacheRec_* FTC_ImageCache; 00717 00718 00719 /*************************************************************************/ 00720 /* */ 00721 /* <Function> */ 00722 /* FTC_ImageCache_New */ 00723 /* */ 00724 /* <Description> */ 00725 /* Create a new glyph image cache. */ 00726 /* */ 00727 /* <Input> */ 00728 /* manager :: The parent manager for the image cache. */ 00729 /* */ 00730 /* <Output> */ 00731 /* acache :: A handle to the new glyph image cache object. */ 00732 /* */ 00733 /* <Return> */ 00734 /* FreeType error code. 0~means success. */ 00735 /* */ 00736 FT_EXPORT( FT_Error ) 00737 FTC_ImageCache_New( FTC_Manager manager, 00738 FTC_ImageCache *acache ); 00739 00740 00741 /*************************************************************************/ 00742 /* */ 00743 /* <Function> */ 00744 /* FTC_ImageCache_Lookup */ 00745 /* */ 00746 /* <Description> */ 00747 /* Retrieve a given glyph image from a glyph image cache. */ 00748 /* */ 00749 /* <Input> */ 00750 /* cache :: A handle to the source glyph image cache. */ 00751 /* */ 00752 /* type :: A pointer to a glyph image type descriptor. */ 00753 /* */ 00754 /* gindex :: The glyph index to retrieve. */ 00755 /* */ 00756 /* <Output> */ 00757 /* aglyph :: The corresponding @FT_Glyph object. 0~in case of */ 00758 /* failure. */ 00759 /* */ 00760 /* anode :: Used to return the address of of the corresponding cache */ 00761 /* node after incrementing its reference count (see note */ 00762 /* below). */ 00763 /* */ 00764 /* <Return> */ 00765 /* FreeType error code. 0~means success. */ 00766 /* */ 00767 /* <Note> */ 00768 /* The returned glyph is owned and managed by the glyph image cache. */ 00769 /* Never try to transform or discard it manually! You can however */ 00770 /* create a copy with @FT_Glyph_Copy and modify the new one. */ 00771 /* */ 00772 /* If `anode' is _not_ NULL, it receives the address of the cache */ 00773 /* node containing the glyph image, after increasing its reference */ 00774 /* count. This ensures that the node (as well as the @FT_Glyph) will */ 00775 /* always be kept in the cache until you call @FTC_Node_Unref to */ 00776 /* `release' it. */ 00777 /* */ 00778 /* If `anode' is NULL, the cache node is left unchanged, which means */ 00779 /* that the @FT_Glyph could be flushed out of the cache on the next */ 00780 /* call to one of the caching sub-system APIs. Don't assume that it */ 00781 /* is persistent! */ 00782 /* */ 00783 FT_EXPORT( FT_Error ) 00784 FTC_ImageCache_Lookup( FTC_ImageCache cache, 00785 FTC_ImageType type, 00786 FT_UInt gindex, 00787 FT_Glyph *aglyph, 00788 FTC_Node *anode ); 00789 00790 00791 /*************************************************************************/ 00792 /* */ 00793 /* <Function> */ 00794 /* FTC_ImageCache_LookupScaler */ 00795 /* */ 00796 /* <Description> */ 00797 /* A variant of @FTC_ImageCache_Lookup that uses an @FTC_ScalerRec */ 00798 /* to specify the face ID and its size. */ 00799 /* */ 00800 /* <Input> */ 00801 /* cache :: A handle to the source glyph image cache. */ 00802 /* */ 00803 /* scaler :: A pointer to a scaler descriptor. */ 00804 /* */ 00805 /* load_flags :: The corresponding load flags. */ 00806 /* */ 00807 /* gindex :: The glyph index to retrieve. */ 00808 /* */ 00809 /* <Output> */ 00810 /* aglyph :: The corresponding @FT_Glyph object. 0~in case of */ 00811 /* failure. */ 00812 /* */ 00813 /* anode :: Used to return the address of of the corresponding */ 00814 /* cache node after incrementing its reference count */ 00815 /* (see note below). */ 00816 /* */ 00817 /* <Return> */ 00818 /* FreeType error code. 0~means success. */ 00819 /* */ 00820 /* <Note> */ 00821 /* The returned glyph is owned and managed by the glyph image cache. */ 00822 /* Never try to transform or discard it manually! You can however */ 00823 /* create a copy with @FT_Glyph_Copy and modify the new one. */ 00824 /* */ 00825 /* If `anode' is _not_ NULL, it receives the address of the cache */ 00826 /* node containing the glyph image, after increasing its reference */ 00827 /* count. This ensures that the node (as well as the @FT_Glyph) will */ 00828 /* always be kept in the cache until you call @FTC_Node_Unref to */ 00829 /* `release' it. */ 00830 /* */ 00831 /* If `anode' is NULL, the cache node is left unchanged, which means */ 00832 /* that the @FT_Glyph could be flushed out of the cache on the next */ 00833 /* call to one of the caching sub-system APIs. Don't assume that it */ 00834 /* is persistent! */ 00835 /* */ 00836 /* Calls to @FT_Set_Char_Size and friends have no effect on cached */ 00837 /* glyphs; you should always use the FreeType cache API instead. */ 00838 /* */ 00839 FT_EXPORT( FT_Error ) 00840 FTC_ImageCache_LookupScaler( FTC_ImageCache cache, 00841 FTC_Scaler scaler, 00842 FT_ULong load_flags, 00843 FT_UInt gindex, 00844 FT_Glyph *aglyph, 00845 FTC_Node *anode ); 00846 00847 00848 /*************************************************************************/ 00849 /* */ 00850 /* <Type> */ 00851 /* FTC_SBit */ 00852 /* */ 00853 /* <Description> */ 00854 /* A handle to a small bitmap descriptor. See the @FTC_SBitRec */ 00855 /* structure for details. */ 00856 /* */ 00857 typedef struct FTC_SBitRec_* FTC_SBit; 00858 00859 00860 /*************************************************************************/ 00861 /* */ 00862 /* <Struct> */ 00863 /* FTC_SBitRec */ 00864 /* */ 00865 /* <Description> */ 00866 /* A very compact structure used to describe a small glyph bitmap. */ 00867 /* */ 00868 /* <Fields> */ 00869 /* width :: The bitmap width in pixels. */ 00870 /* */ 00871 /* height :: The bitmap height in pixels. */ 00872 /* */ 00873 /* left :: The horizontal distance from the pen position to the */ 00874 /* left bitmap border (a.k.a. `left side bearing', or */ 00875 /* `lsb'). */ 00876 /* */ 00877 /* top :: The vertical distance from the pen position (on the */ 00878 /* baseline) to the upper bitmap border (a.k.a. `top */ 00879 /* side bearing'). The distance is positive for upwards */ 00880 /* y~coordinates. */ 00881 /* */ 00882 /* format :: The format of the glyph bitmap (monochrome or gray). */ 00883 /* */ 00884 /* max_grays :: Maximum gray level value (in the range 1 to~255). */ 00885 /* */ 00886 /* pitch :: The number of bytes per bitmap line. May be positive */ 00887 /* or negative. */ 00888 /* */ 00889 /* xadvance :: The horizontal advance width in pixels. */ 00890 /* */ 00891 /* yadvance :: The vertical advance height in pixels. */ 00892 /* */ 00893 /* buffer :: A pointer to the bitmap pixels. */ 00894 /* */ 00895 typedef struct FTC_SBitRec_ 00896 { 00897 FT_Byte width; 00898 FT_Byte height; 00899 FT_Char left; 00900 FT_Char top; 00901 00902 FT_Byte format; 00903 FT_Byte max_grays; 00904 FT_Short pitch; 00905 FT_Char xadvance; 00906 FT_Char yadvance; 00907 00908 FT_Byte* buffer; 00909 00910 } FTC_SBitRec; 00911 00912 00913 /*************************************************************************/ 00914 /* */ 00915 /* <Type> */ 00916 /* FTC_SBitCache */ 00917 /* */ 00918 /* <Description> */ 00919 /* A handle to a small bitmap cache. These are special cache objects */ 00920 /* used to store small glyph bitmaps (and anti-aliased pixmaps) in a */ 00921 /* much more efficient way than the traditional glyph image cache */ 00922 /* implemented by @FTC_ImageCache. */ 00923 /* */ 00924 typedef struct FTC_SBitCacheRec_* FTC_SBitCache; 00925 00926 00927 /*************************************************************************/ 00928 /* */ 00929 /* <Function> */ 00930 /* FTC_SBitCache_New */ 00931 /* */ 00932 /* <Description> */ 00933 /* Create a new cache to store small glyph bitmaps. */ 00934 /* */ 00935 /* <Input> */ 00936 /* manager :: A handle to the source cache manager. */ 00937 /* */ 00938 /* <Output> */ 00939 /* acache :: A handle to the new sbit cache. NULL in case of error. */ 00940 /* */ 00941 /* <Return> */ 00942 /* FreeType error code. 0~means success. */ 00943 /* */ 00944 FT_EXPORT( FT_Error ) 00945 FTC_SBitCache_New( FTC_Manager manager, 00946 FTC_SBitCache *acache ); 00947 00948 00949 /*************************************************************************/ 00950 /* */ 00951 /* <Function> */ 00952 /* FTC_SBitCache_Lookup */ 00953 /* */ 00954 /* <Description> */ 00955 /* Look up a given small glyph bitmap in a given sbit cache and */ 00956 /* `lock' it to prevent its flushing from the cache until needed. */ 00957 /* */ 00958 /* <Input> */ 00959 /* cache :: A handle to the source sbit cache. */ 00960 /* */ 00961 /* type :: A pointer to the glyph image type descriptor. */ 00962 /* */ 00963 /* gindex :: The glyph index. */ 00964 /* */ 00965 /* <Output> */ 00966 /* sbit :: A handle to a small bitmap descriptor. */ 00967 /* */ 00968 /* anode :: Used to return the address of of the corresponding cache */ 00969 /* node after incrementing its reference count (see note */ 00970 /* below). */ 00971 /* */ 00972 /* <Return> */ 00973 /* FreeType error code. 0~means success. */ 00974 /* */ 00975 /* <Note> */ 00976 /* The small bitmap descriptor and its bit buffer are owned by the */ 00977 /* cache and should never be freed by the application. They might */ 00978 /* as well disappear from memory on the next cache lookup, so don't */ 00979 /* treat them as persistent data. */ 00980 /* */ 00981 /* The descriptor's `buffer' field is set to~0 to indicate a missing */ 00982 /* glyph bitmap. */ 00983 /* */ 00984 /* If `anode' is _not_ NULL, it receives the address of the cache */ 00985 /* node containing the bitmap, after increasing its reference count. */ 00986 /* This ensures that the node (as well as the image) will always be */ 00987 /* kept in the cache until you call @FTC_Node_Unref to `release' it. */ 00988 /* */ 00989 /* If `anode' is NULL, the cache node is left unchanged, which means */ 00990 /* that the bitmap could be flushed out of the cache on the next */ 00991 /* call to one of the caching sub-system APIs. Don't assume that it */ 00992 /* is persistent! */ 00993 /* */ 00994 FT_EXPORT( FT_Error ) 00995 FTC_SBitCache_Lookup( FTC_SBitCache cache, 00996 FTC_ImageType type, 00997 FT_UInt gindex, 00998 FTC_SBit *sbit, 00999 FTC_Node *anode ); 01000 01001 01002 /*************************************************************************/ 01003 /* */ 01004 /* <Function> */ 01005 /* FTC_SBitCache_LookupScaler */ 01006 /* */ 01007 /* <Description> */ 01008 /* A variant of @FTC_SBitCache_Lookup that uses an @FTC_ScalerRec */ 01009 /* to specify the face ID and its size. */ 01010 /* */ 01011 /* <Input> */ 01012 /* cache :: A handle to the source sbit cache. */ 01013 /* */ 01014 /* scaler :: A pointer to the scaler descriptor. */ 01015 /* */ 01016 /* load_flags :: The corresponding load flags. */ 01017 /* */ 01018 /* gindex :: The glyph index. */ 01019 /* */ 01020 /* <Output> */ 01021 /* sbit :: A handle to a small bitmap descriptor. */ 01022 /* */ 01023 /* anode :: Used to return the address of of the corresponding */ 01024 /* cache node after incrementing its reference count */ 01025 /* (see note below). */ 01026 /* */ 01027 /* <Return> */ 01028 /* FreeType error code. 0~means success. */ 01029 /* */ 01030 /* <Note> */ 01031 /* The small bitmap descriptor and its bit buffer are owned by the */ 01032 /* cache and should never be freed by the application. They might */ 01033 /* as well disappear from memory on the next cache lookup, so don't */ 01034 /* treat them as persistent data. */ 01035 /* */ 01036 /* The descriptor's `buffer' field is set to~0 to indicate a missing */ 01037 /* glyph bitmap. */ 01038 /* */ 01039 /* If `anode' is _not_ NULL, it receives the address of the cache */ 01040 /* node containing the bitmap, after increasing its reference count. */ 01041 /* This ensures that the node (as well as the image) will always be */ 01042 /* kept in the cache until you call @FTC_Node_Unref to `release' it. */ 01043 /* */ 01044 /* If `anode' is NULL, the cache node is left unchanged, which means */ 01045 /* that the bitmap could be flushed out of the cache on the next */ 01046 /* call to one of the caching sub-system APIs. Don't assume that it */ 01047 /* is persistent! */ 01048 /* */ 01049 FT_EXPORT( FT_Error ) 01050 FTC_SBitCache_LookupScaler( FTC_SBitCache cache, 01051 FTC_Scaler scaler, 01052 FT_ULong load_flags, 01053 FT_UInt gindex, 01054 FTC_SBit *sbit, 01055 FTC_Node *anode ); 01056 01057 01058 /* */ 01059 01060 #ifdef FT_CONFIG_OPTION_OLD_INTERNALS 01061 01062 /*@***********************************************************************/ 01063 /* */ 01064 /* <Struct> */ 01065 /* FTC_FontRec */ 01066 /* */ 01067 /* <Description> */ 01068 /* A simple structure used to describe a given `font' to the cache */ 01069 /* manager. Note that a `font' is the combination of a given face */ 01070 /* with a given character size. */ 01071 /* */ 01072 /* <Fields> */ 01073 /* face_id :: The ID of the face to use. */ 01074 /* */ 01075 /* pix_width :: The character width in integer pixels. */ 01076 /* */ 01077 /* pix_height :: The character height in integer pixels. */ 01078 /* */ 01079 typedef struct FTC_FontRec_ 01080 { 01081 FTC_FaceID face_id; 01082 FT_UShort pix_width; 01083 FT_UShort pix_height; 01084 01085 } FTC_FontRec; 01086 01087 01088 /* */ 01089 01090 01091 #define FTC_FONT_COMPARE( f1, f2 ) \ 01092 ( (f1)->face_id == (f2)->face_id && \ 01093 (f1)->pix_width == (f2)->pix_width && \ 01094 (f1)->pix_height == (f2)->pix_height ) 01095 01096 #define FTC_FONT_HASH( f ) \ 01097 (FT_UInt32)( FTC_FACE_ID_HASH((f)->face_id) ^ \ 01098 ((f)->pix_width << 8) ^ \ 01099 ((f)->pix_height) ) 01100 01101 typedef FTC_FontRec* FTC_Font; 01102 01103 01104 FT_EXPORT( FT_Error ) 01105 FTC_Manager_Lookup_Face( FTC_Manager manager, 01106 FTC_FaceID face_id, 01107 FT_Face *aface ); 01108 01109 FT_EXPORT( FT_Error ) 01110 FTC_Manager_Lookup_Size( FTC_Manager manager, 01111 FTC_Font font, 01112 FT_Face *aface, 01113 FT_Size *asize ); 01114 01115 #endif /* FT_CONFIG_OPTION_OLD_INTERNALS */ 01116 01117 01118 /* */ 01119 01120 FT_END_HEADER 01121 01122 #endif /* __FTCACHE_H__ */ 01123 01124 01125 /* END */
1.5.1