vrshoot
diff libs/ft2static/freetype/ftcache.h @ 0:b2f14e535253
initial commit
| author | John Tsiombikas <nuclear@member.fsf.org> |
|---|---|
| date | Sat, 01 Feb 2014 19:58:19 +0200 |
| parents | |
| children |
line diff
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/libs/ft2static/freetype/ftcache.h Sat Feb 01 19:58:19 2014 +0200 1.3 @@ -0,0 +1,1140 @@ 1.4 +/***************************************************************************/ 1.5 +/* */ 1.6 +/* ftcache.h */ 1.7 +/* */ 1.8 +/* FreeType Cache subsystem (specification). */ 1.9 +/* */ 1.10 +/* Copyright 1996-2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2010 by */ 1.11 +/* David Turner, Robert Wilhelm, and Werner Lemberg. */ 1.12 +/* */ 1.13 +/* This file is part of the FreeType project, and may only be used, */ 1.14 +/* modified, and distributed under the terms of the FreeType project */ 1.15 +/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ 1.16 +/* this file you indicate that you have read the license and */ 1.17 +/* understand and accept it fully. */ 1.18 +/* */ 1.19 +/***************************************************************************/ 1.20 + 1.21 + 1.22 +#ifndef __FTCACHE_H__ 1.23 +#define __FTCACHE_H__ 1.24 + 1.25 + 1.26 +#include <ft2build.h> 1.27 +#include FT_GLYPH_H 1.28 + 1.29 + 1.30 +FT_BEGIN_HEADER 1.31 + 1.32 + 1.33 + /************************************************************************* 1.34 + * 1.35 + * <Section> 1.36 + * cache_subsystem 1.37 + * 1.38 + * <Title> 1.39 + * Cache Sub-System 1.40 + * 1.41 + * <Abstract> 1.42 + * How to cache face, size, and glyph data with FreeType~2. 1.43 + * 1.44 + * <Description> 1.45 + * This section describes the FreeType~2 cache sub-system, which is used 1.46 + * to limit the number of concurrently opened @FT_Face and @FT_Size 1.47 + * objects, as well as caching information like character maps and glyph 1.48 + * images while limiting their maximum memory usage. 1.49 + * 1.50 + * Note that all types and functions begin with the `FTC_' prefix. 1.51 + * 1.52 + * The cache is highly portable and thus doesn't know anything about the 1.53 + * fonts installed on your system, or how to access them. This implies 1.54 + * the following scheme: 1.55 + * 1.56 + * First, available or installed font faces are uniquely identified by 1.57 + * @FTC_FaceID values, provided to the cache by the client. Note that 1.58 + * the cache only stores and compares these values, and doesn't try to 1.59 + * interpret them in any way. 1.60 + * 1.61 + * Second, the cache calls, only when needed, a client-provided function 1.62 + * to convert an @FTC_FaceID into a new @FT_Face object. The latter is 1.63 + * then completely managed by the cache, including its termination 1.64 + * through @FT_Done_Face. To monitor termination of face objects, the 1.65 + * finalizer callback in the `generic' field of the @FT_Face object can 1.66 + * be used, which might also be used to store the @FTC_FaceID of the 1.67 + * face. 1.68 + * 1.69 + * Clients are free to map face IDs to anything else. The most simple 1.70 + * usage is to associate them to a (pathname,face_index) pair that is 1.71 + * used to call @FT_New_Face. However, more complex schemes are also 1.72 + * possible. 1.73 + * 1.74 + * Note that for the cache to work correctly, the face ID values must be 1.75 + * *persistent*, which means that the contents they point to should not 1.76 + * change at runtime, or that their value should not become invalid. 1.77 + * 1.78 + * If this is unavoidable (e.g., when a font is uninstalled at runtime), 1.79 + * you should call @FTC_Manager_RemoveFaceID as soon as possible, to let 1.80 + * the cache get rid of any references to the old @FTC_FaceID it may 1.81 + * keep internally. Failure to do so will lead to incorrect behaviour 1.82 + * or even crashes. 1.83 + * 1.84 + * To use the cache, start with calling @FTC_Manager_New to create a new 1.85 + * @FTC_Manager object, which models a single cache instance. You can 1.86 + * then look up @FT_Face and @FT_Size objects with 1.87 + * @FTC_Manager_LookupFace and @FTC_Manager_LookupSize, respectively. 1.88 + * 1.89 + * If you want to use the charmap caching, call @FTC_CMapCache_New, then 1.90 + * later use @FTC_CMapCache_Lookup to perform the equivalent of 1.91 + * @FT_Get_Char_Index, only much faster. 1.92 + * 1.93 + * If you want to use the @FT_Glyph caching, call @FTC_ImageCache, then 1.94 + * later use @FTC_ImageCache_Lookup to retrieve the corresponding 1.95 + * @FT_Glyph objects from the cache. 1.96 + * 1.97 + * If you need lots of small bitmaps, it is much more memory efficient 1.98 + * to call @FTC_SBitCache_New followed by @FTC_SBitCache_Lookup. This 1.99 + * returns @FTC_SBitRec structures, which are used to store small 1.100 + * bitmaps directly. (A small bitmap is one whose metrics and 1.101 + * dimensions all fit into 8-bit integers). 1.102 + * 1.103 + * We hope to also provide a kerning cache in the near future. 1.104 + * 1.105 + * 1.106 + * <Order> 1.107 + * FTC_Manager 1.108 + * FTC_FaceID 1.109 + * FTC_Face_Requester 1.110 + * 1.111 + * FTC_Manager_New 1.112 + * FTC_Manager_Reset 1.113 + * FTC_Manager_Done 1.114 + * FTC_Manager_LookupFace 1.115 + * FTC_Manager_LookupSize 1.116 + * FTC_Manager_RemoveFaceID 1.117 + * 1.118 + * FTC_Node 1.119 + * FTC_Node_Unref 1.120 + * 1.121 + * FTC_ImageCache 1.122 + * FTC_ImageCache_New 1.123 + * FTC_ImageCache_Lookup 1.124 + * 1.125 + * FTC_SBit 1.126 + * FTC_SBitCache 1.127 + * FTC_SBitCache_New 1.128 + * FTC_SBitCache_Lookup 1.129 + * 1.130 + * FTC_CMapCache 1.131 + * FTC_CMapCache_New 1.132 + * FTC_CMapCache_Lookup 1.133 + * 1.134 + *************************************************************************/ 1.135 + 1.136 + 1.137 + /*************************************************************************/ 1.138 + /*************************************************************************/ 1.139 + /*************************************************************************/ 1.140 + /***** *****/ 1.141 + /***** BASIC TYPE DEFINITIONS *****/ 1.142 + /***** *****/ 1.143 + /*************************************************************************/ 1.144 + /*************************************************************************/ 1.145 + /*************************************************************************/ 1.146 + 1.147 + 1.148 + /************************************************************************* 1.149 + * 1.150 + * @type: FTC_FaceID 1.151 + * 1.152 + * @description: 1.153 + * An opaque pointer type that is used to identity face objects. The 1.154 + * contents of such objects is application-dependent. 1.155 + * 1.156 + * These pointers are typically used to point to a user-defined 1.157 + * structure containing a font file path, and face index. 1.158 + * 1.159 + * @note: 1.160 + * Never use NULL as a valid @FTC_FaceID. 1.161 + * 1.162 + * Face IDs are passed by the client to the cache manager, which calls, 1.163 + * when needed, the @FTC_Face_Requester to translate them into new 1.164 + * @FT_Face objects. 1.165 + * 1.166 + * If the content of a given face ID changes at runtime, or if the value 1.167 + * becomes invalid (e.g., when uninstalling a font), you should 1.168 + * immediately call @FTC_Manager_RemoveFaceID before any other cache 1.169 + * function. 1.170 + * 1.171 + * Failure to do so will result in incorrect behaviour or even 1.172 + * memory leaks and crashes. 1.173 + */ 1.174 + typedef FT_Pointer FTC_FaceID; 1.175 + 1.176 + 1.177 + /************************************************************************ 1.178 + * 1.179 + * @functype: 1.180 + * FTC_Face_Requester 1.181 + * 1.182 + * @description: 1.183 + * A callback function provided by client applications. It is used by 1.184 + * the cache manager to translate a given @FTC_FaceID into a new valid 1.185 + * @FT_Face object, on demand. 1.186 + * 1.187 + * <Input> 1.188 + * face_id :: 1.189 + * The face ID to resolve. 1.190 + * 1.191 + * library :: 1.192 + * A handle to a FreeType library object. 1.193 + * 1.194 + * req_data :: 1.195 + * Application-provided request data (see note below). 1.196 + * 1.197 + * <Output> 1.198 + * aface :: 1.199 + * A new @FT_Face handle. 1.200 + * 1.201 + * <Return> 1.202 + * FreeType error code. 0~means success. 1.203 + * 1.204 + * <Note> 1.205 + * The third parameter `req_data' is the same as the one passed by the 1.206 + * client when @FTC_Manager_New is called. 1.207 + * 1.208 + * The face requester should not perform funny things on the returned 1.209 + * face object, like creating a new @FT_Size for it, or setting a 1.210 + * transformation through @FT_Set_Transform! 1.211 + */ 1.212 + typedef FT_Error 1.213 + (*FTC_Face_Requester)( FTC_FaceID face_id, 1.214 + FT_Library library, 1.215 + FT_Pointer request_data, 1.216 + FT_Face* aface ); 1.217 + 1.218 + /* */ 1.219 + 1.220 +#ifdef FT_CONFIG_OPTION_OLD_INTERNALS 1.221 + 1.222 + /* these macros are incompatible with LLP64, should not be used */ 1.223 + 1.224 +#define FT_POINTER_TO_ULONG( p ) ( (FT_ULong)(FT_Pointer)(p) ) 1.225 + 1.226 +#define FTC_FACE_ID_HASH( i ) \ 1.227 + ((FT_UInt32)(( FT_POINTER_TO_ULONG( i ) >> 3 ) ^ \ 1.228 + ( FT_POINTER_TO_ULONG( i ) << 7 ) ) ) 1.229 + 1.230 +#endif /* FT_CONFIG_OPTION_OLD_INTERNALS */ 1.231 + 1.232 + /*************************************************************************/ 1.233 + /*************************************************************************/ 1.234 + /*************************************************************************/ 1.235 + /***** *****/ 1.236 + /***** CACHE MANAGER OBJECT *****/ 1.237 + /***** *****/ 1.238 + /*************************************************************************/ 1.239 + /*************************************************************************/ 1.240 + /*************************************************************************/ 1.241 + 1.242 + 1.243 + /*************************************************************************/ 1.244 + /* */ 1.245 + /* <Type> */ 1.246 + /* FTC_Manager */ 1.247 + /* */ 1.248 + /* <Description> */ 1.249 + /* This object corresponds to one instance of the cache-subsystem. */ 1.250 + /* It is used to cache one or more @FT_Face objects, along with */ 1.251 + /* corresponding @FT_Size objects. */ 1.252 + /* */ 1.253 + /* The manager intentionally limits the total number of opened */ 1.254 + /* @FT_Face and @FT_Size objects to control memory usage. See the */ 1.255 + /* `max_faces' and `max_sizes' parameters of @FTC_Manager_New. */ 1.256 + /* */ 1.257 + /* The manager is also used to cache `nodes' of various types while */ 1.258 + /* limiting their total memory usage. */ 1.259 + /* */ 1.260 + /* All limitations are enforced by keeping lists of managed objects */ 1.261 + /* in most-recently-used order, and flushing old nodes to make room */ 1.262 + /* for new ones. */ 1.263 + /* */ 1.264 + typedef struct FTC_ManagerRec_* FTC_Manager; 1.265 + 1.266 + 1.267 + /*************************************************************************/ 1.268 + /* */ 1.269 + /* <Type> */ 1.270 + /* FTC_Node */ 1.271 + /* */ 1.272 + /* <Description> */ 1.273 + /* An opaque handle to a cache node object. Each cache node is */ 1.274 + /* reference-counted. A node with a count of~0 might be flushed */ 1.275 + /* out of a full cache whenever a lookup request is performed. */ 1.276 + /* */ 1.277 + /* If you look up nodes, you have the ability to `acquire' them, */ 1.278 + /* i.e., to increment their reference count. This will prevent the */ 1.279 + /* node from being flushed out of the cache until you explicitly */ 1.280 + /* `release' it (see @FTC_Node_Unref). */ 1.281 + /* */ 1.282 + /* See also @FTC_SBitCache_Lookup and @FTC_ImageCache_Lookup. */ 1.283 + /* */ 1.284 + typedef struct FTC_NodeRec_* FTC_Node; 1.285 + 1.286 + 1.287 + /*************************************************************************/ 1.288 + /* */ 1.289 + /* <Function> */ 1.290 + /* FTC_Manager_New */ 1.291 + /* */ 1.292 + /* <Description> */ 1.293 + /* Create a new cache manager. */ 1.294 + /* */ 1.295 + /* <Input> */ 1.296 + /* library :: The parent FreeType library handle to use. */ 1.297 + /* */ 1.298 + /* max_faces :: Maximum number of opened @FT_Face objects managed by */ 1.299 + /* this cache instance. Use~0 for defaults. */ 1.300 + /* */ 1.301 + /* max_sizes :: Maximum number of opened @FT_Size objects managed by */ 1.302 + /* this cache instance. Use~0 for defaults. */ 1.303 + /* */ 1.304 + /* max_bytes :: Maximum number of bytes to use for cached data nodes. */ 1.305 + /* Use~0 for defaults. Note that this value does not */ 1.306 + /* account for managed @FT_Face and @FT_Size objects. */ 1.307 + /* */ 1.308 + /* requester :: An application-provided callback used to translate */ 1.309 + /* face IDs into real @FT_Face objects. */ 1.310 + /* */ 1.311 + /* req_data :: A generic pointer that is passed to the requester */ 1.312 + /* each time it is called (see @FTC_Face_Requester). */ 1.313 + /* */ 1.314 + /* <Output> */ 1.315 + /* amanager :: A handle to a new manager object. 0~in case of */ 1.316 + /* failure. */ 1.317 + /* */ 1.318 + /* <Return> */ 1.319 + /* FreeType error code. 0~means success. */ 1.320 + /* */ 1.321 + FT_EXPORT( FT_Error ) 1.322 + FTC_Manager_New( FT_Library library, 1.323 + FT_UInt max_faces, 1.324 + FT_UInt max_sizes, 1.325 + FT_ULong max_bytes, 1.326 + FTC_Face_Requester requester, 1.327 + FT_Pointer req_data, 1.328 + FTC_Manager *amanager ); 1.329 + 1.330 + 1.331 + /*************************************************************************/ 1.332 + /* */ 1.333 + /* <Function> */ 1.334 + /* FTC_Manager_Reset */ 1.335 + /* */ 1.336 + /* <Description> */ 1.337 + /* Empty a given cache manager. This simply gets rid of all the */ 1.338 + /* currently cached @FT_Face and @FT_Size objects within the manager. */ 1.339 + /* */ 1.340 + /* <InOut> */ 1.341 + /* manager :: A handle to the manager. */ 1.342 + /* */ 1.343 + FT_EXPORT( void ) 1.344 + FTC_Manager_Reset( FTC_Manager manager ); 1.345 + 1.346 + 1.347 + /*************************************************************************/ 1.348 + /* */ 1.349 + /* <Function> */ 1.350 + /* FTC_Manager_Done */ 1.351 + /* */ 1.352 + /* <Description> */ 1.353 + /* Destroy a given manager after emptying it. */ 1.354 + /* */ 1.355 + /* <Input> */ 1.356 + /* manager :: A handle to the target cache manager object. */ 1.357 + /* */ 1.358 + FT_EXPORT( void ) 1.359 + FTC_Manager_Done( FTC_Manager manager ); 1.360 + 1.361 + 1.362 + /*************************************************************************/ 1.363 + /* */ 1.364 + /* <Function> */ 1.365 + /* FTC_Manager_LookupFace */ 1.366 + /* */ 1.367 + /* <Description> */ 1.368 + /* Retrieve the @FT_Face object that corresponds to a given face ID */ 1.369 + /* through a cache manager. */ 1.370 + /* */ 1.371 + /* <Input> */ 1.372 + /* manager :: A handle to the cache manager. */ 1.373 + /* */ 1.374 + /* face_id :: The ID of the face object. */ 1.375 + /* */ 1.376 + /* <Output> */ 1.377 + /* aface :: A handle to the face object. */ 1.378 + /* */ 1.379 + /* <Return> */ 1.380 + /* FreeType error code. 0~means success. */ 1.381 + /* */ 1.382 + /* <Note> */ 1.383 + /* The returned @FT_Face object is always owned by the manager. You */ 1.384 + /* should never try to discard it yourself. */ 1.385 + /* */ 1.386 + /* The @FT_Face object doesn't necessarily have a current size object */ 1.387 + /* (i.e., face->size can be 0). If you need a specific `font size', */ 1.388 + /* use @FTC_Manager_LookupSize instead. */ 1.389 + /* */ 1.390 + /* Never change the face's transformation matrix (i.e., never call */ 1.391 + /* the @FT_Set_Transform function) on a returned face! If you need */ 1.392 + /* to transform glyphs, do it yourself after glyph loading. */ 1.393 + /* */ 1.394 + /* When you perform a lookup, out-of-memory errors are detected */ 1.395 + /* _within_ the lookup and force incremental flushes of the cache */ 1.396 + /* until enough memory is released for the lookup to succeed. */ 1.397 + /* */ 1.398 + /* If a lookup fails with `FT_Err_Out_Of_Memory' the cache has */ 1.399 + /* already been completely flushed, and still no memory was available */ 1.400 + /* for the operation. */ 1.401 + /* */ 1.402 + FT_EXPORT( FT_Error ) 1.403 + FTC_Manager_LookupFace( FTC_Manager manager, 1.404 + FTC_FaceID face_id, 1.405 + FT_Face *aface ); 1.406 + 1.407 + 1.408 + /*************************************************************************/ 1.409 + /* */ 1.410 + /* <Struct> */ 1.411 + /* FTC_ScalerRec */ 1.412 + /* */ 1.413 + /* <Description> */ 1.414 + /* A structure used to describe a given character size in either */ 1.415 + /* pixels or points to the cache manager. See */ 1.416 + /* @FTC_Manager_LookupSize. */ 1.417 + /* */ 1.418 + /* <Fields> */ 1.419 + /* face_id :: The source face ID. */ 1.420 + /* */ 1.421 + /* width :: The character width. */ 1.422 + /* */ 1.423 + /* height :: The character height. */ 1.424 + /* */ 1.425 + /* pixel :: A Boolean. If 1, the `width' and `height' fields are */ 1.426 + /* interpreted as integer pixel character sizes. */ 1.427 + /* Otherwise, they are expressed as 1/64th of points. */ 1.428 + /* */ 1.429 + /* x_res :: Only used when `pixel' is value~0 to indicate the */ 1.430 + /* horizontal resolution in dpi. */ 1.431 + /* */ 1.432 + /* y_res :: Only used when `pixel' is value~0 to indicate the */ 1.433 + /* vertical resolution in dpi. */ 1.434 + /* */ 1.435 + /* <Note> */ 1.436 + /* This type is mainly used to retrieve @FT_Size objects through the */ 1.437 + /* cache manager. */ 1.438 + /* */ 1.439 + typedef struct FTC_ScalerRec_ 1.440 + { 1.441 + FTC_FaceID face_id; 1.442 + FT_UInt width; 1.443 + FT_UInt height; 1.444 + FT_Int pixel; 1.445 + FT_UInt x_res; 1.446 + FT_UInt y_res; 1.447 + 1.448 + } FTC_ScalerRec; 1.449 + 1.450 + 1.451 + /*************************************************************************/ 1.452 + /* */ 1.453 + /* <Struct> */ 1.454 + /* FTC_Scaler */ 1.455 + /* */ 1.456 + /* <Description> */ 1.457 + /* A handle to an @FTC_ScalerRec structure. */ 1.458 + /* */ 1.459 + typedef struct FTC_ScalerRec_* FTC_Scaler; 1.460 + 1.461 + 1.462 + /*************************************************************************/ 1.463 + /* */ 1.464 + /* <Function> */ 1.465 + /* FTC_Manager_LookupSize */ 1.466 + /* */ 1.467 + /* <Description> */ 1.468 + /* Retrieve the @FT_Size object that corresponds to a given */ 1.469 + /* @FTC_ScalerRec pointer through a cache manager. */ 1.470 + /* */ 1.471 + /* <Input> */ 1.472 + /* manager :: A handle to the cache manager. */ 1.473 + /* */ 1.474 + /* scaler :: A scaler handle. */ 1.475 + /* */ 1.476 + /* <Output> */ 1.477 + /* asize :: A handle to the size object. */ 1.478 + /* */ 1.479 + /* <Return> */ 1.480 + /* FreeType error code. 0~means success. */ 1.481 + /* */ 1.482 + /* <Note> */ 1.483 + /* The returned @FT_Size object is always owned by the manager. You */ 1.484 + /* should never try to discard it by yourself. */ 1.485 + /* */ 1.486 + /* You can access the parent @FT_Face object simply as `size->face' */ 1.487 + /* if you need it. Note that this object is also owned by the */ 1.488 + /* manager. */ 1.489 + /* */ 1.490 + /* <Note> */ 1.491 + /* When you perform a lookup, out-of-memory errors are detected */ 1.492 + /* _within_ the lookup and force incremental flushes of the cache */ 1.493 + /* until enough memory is released for the lookup to succeed. */ 1.494 + /* */ 1.495 + /* If a lookup fails with `FT_Err_Out_Of_Memory' the cache has */ 1.496 + /* already been completely flushed, and still no memory is available */ 1.497 + /* for the operation. */ 1.498 + /* */ 1.499 + FT_EXPORT( FT_Error ) 1.500 + FTC_Manager_LookupSize( FTC_Manager manager, 1.501 + FTC_Scaler scaler, 1.502 + FT_Size *asize ); 1.503 + 1.504 + 1.505 + /*************************************************************************/ 1.506 + /* */ 1.507 + /* <Function> */ 1.508 + /* FTC_Node_Unref */ 1.509 + /* */ 1.510 + /* <Description> */ 1.511 + /* Decrement a cache node's internal reference count. When the count */ 1.512 + /* reaches 0, it is not destroyed but becomes eligible for subsequent */ 1.513 + /* cache flushes. */ 1.514 + /* */ 1.515 + /* <Input> */ 1.516 + /* node :: The cache node handle. */ 1.517 + /* */ 1.518 + /* manager :: The cache manager handle. */ 1.519 + /* */ 1.520 + FT_EXPORT( void ) 1.521 + FTC_Node_Unref( FTC_Node node, 1.522 + FTC_Manager manager ); 1.523 + 1.524 + 1.525 + /************************************************************************* 1.526 + * 1.527 + * @function: 1.528 + * FTC_Manager_RemoveFaceID 1.529 + * 1.530 + * @description: 1.531 + * A special function used to indicate to the cache manager that 1.532 + * a given @FTC_FaceID is no longer valid, either because its 1.533 + * content changed, or because it was deallocated or uninstalled. 1.534 + * 1.535 + * @input: 1.536 + * manager :: 1.537 + * The cache manager handle. 1.538 + * 1.539 + * face_id :: 1.540 + * The @FTC_FaceID to be removed. 1.541 + * 1.542 + * @note: 1.543 + * This function flushes all nodes from the cache corresponding to this 1.544 + * `face_id', with the exception of nodes with a non-null reference 1.545 + * count. 1.546 + * 1.547 + * Such nodes are however modified internally so as to never appear 1.548 + * in later lookups with the same `face_id' value, and to be immediately 1.549 + * destroyed when released by all their users. 1.550 + * 1.551 + */ 1.552 + FT_EXPORT( void ) 1.553 + FTC_Manager_RemoveFaceID( FTC_Manager manager, 1.554 + FTC_FaceID face_id ); 1.555 + 1.556 + 1.557 + /*************************************************************************/ 1.558 + /* */ 1.559 + /* <Section> */ 1.560 + /* cache_subsystem */ 1.561 + /* */ 1.562 + /*************************************************************************/ 1.563 + 1.564 + /************************************************************************* 1.565 + * 1.566 + * @type: 1.567 + * FTC_CMapCache 1.568 + * 1.569 + * @description: 1.570 + * An opaque handle used to model a charmap cache. This cache is to 1.571 + * hold character codes -> glyph indices mappings. 1.572 + * 1.573 + */ 1.574 + typedef struct FTC_CMapCacheRec_* FTC_CMapCache; 1.575 + 1.576 + 1.577 + /************************************************************************* 1.578 + * 1.579 + * @function: 1.580 + * FTC_CMapCache_New 1.581 + * 1.582 + * @description: 1.583 + * Create a new charmap cache. 1.584 + * 1.585 + * @input: 1.586 + * manager :: 1.587 + * A handle to the cache manager. 1.588 + * 1.589 + * @output: 1.590 + * acache :: 1.591 + * A new cache handle. NULL in case of error. 1.592 + * 1.593 + * @return: 1.594 + * FreeType error code. 0~means success. 1.595 + * 1.596 + * @note: 1.597 + * Like all other caches, this one will be destroyed with the cache 1.598 + * manager. 1.599 + * 1.600 + */ 1.601 + FT_EXPORT( FT_Error ) 1.602 + FTC_CMapCache_New( FTC_Manager manager, 1.603 + FTC_CMapCache *acache ); 1.604 + 1.605 + 1.606 + /************************************************************************ 1.607 + * 1.608 + * @function: 1.609 + * FTC_CMapCache_Lookup 1.610 + * 1.611 + * @description: 1.612 + * Translate a character code into a glyph index, using the charmap 1.613 + * cache. 1.614 + * 1.615 + * @input: 1.616 + * cache :: 1.617 + * A charmap cache handle. 1.618 + * 1.619 + * face_id :: 1.620 + * The source face ID. 1.621 + * 1.622 + * cmap_index :: 1.623 + * The index of the charmap in the source face. Any negative value 1.624 + * means to use the cache @FT_Face's default charmap. 1.625 + * 1.626 + * char_code :: 1.627 + * The character code (in the corresponding charmap). 1.628 + * 1.629 + * @return: 1.630 + * Glyph index. 0~means `no glyph'. 1.631 + * 1.632 + */ 1.633 + FT_EXPORT( FT_UInt ) 1.634 + FTC_CMapCache_Lookup( FTC_CMapCache cache, 1.635 + FTC_FaceID face_id, 1.636 + FT_Int cmap_index, 1.637 + FT_UInt32 char_code ); 1.638 + 1.639 + 1.640 + /*************************************************************************/ 1.641 + /* */ 1.642 + /* <Section> */ 1.643 + /* cache_subsystem */ 1.644 + /* */ 1.645 + /*************************************************************************/ 1.646 + 1.647 + 1.648 + /*************************************************************************/ 1.649 + /*************************************************************************/ 1.650 + /*************************************************************************/ 1.651 + /***** *****/ 1.652 + /***** IMAGE CACHE OBJECT *****/ 1.653 + /***** *****/ 1.654 + /*************************************************************************/ 1.655 + /*************************************************************************/ 1.656 + /*************************************************************************/ 1.657 + 1.658 + 1.659 + /************************************************************************* 1.660 + * 1.661 + * @struct: 1.662 + * FTC_ImageTypeRec 1.663 + * 1.664 + * @description: 1.665 + * A structure used to model the type of images in a glyph cache. 1.666 + * 1.667 + * @fields: 1.668 + * face_id :: 1.669 + * The face ID. 1.670 + * 1.671 + * width :: 1.672 + * The width in pixels. 1.673 + * 1.674 + * height :: 1.675 + * The height in pixels. 1.676 + * 1.677 + * flags :: 1.678 + * The load flags, as in @FT_Load_Glyph. 1.679 + * 1.680 + */ 1.681 + typedef struct FTC_ImageTypeRec_ 1.682 + { 1.683 + FTC_FaceID face_id; 1.684 + FT_Int width; 1.685 + FT_Int height; 1.686 + FT_Int32 flags; 1.687 + 1.688 + } FTC_ImageTypeRec; 1.689 + 1.690 + 1.691 + /************************************************************************* 1.692 + * 1.693 + * @type: 1.694 + * FTC_ImageType 1.695 + * 1.696 + * @description: 1.697 + * A handle to an @FTC_ImageTypeRec structure. 1.698 + * 1.699 + */ 1.700 + typedef struct FTC_ImageTypeRec_* FTC_ImageType; 1.701 + 1.702 + 1.703 + /* */ 1.704 + 1.705 + 1.706 +#define FTC_IMAGE_TYPE_COMPARE( d1, d2 ) \ 1.707 + ( (d1)->face_id == (d2)->face_id && \ 1.708 + (d1)->width == (d2)->width && \ 1.709 + (d1)->flags == (d2)->flags ) 1.710 + 1.711 +#ifdef FT_CONFIG_OPTION_OLD_INTERNALS 1.712 + 1.713 + /* this macro is incompatible with LLP64, should not be used */ 1.714 + 1.715 +#define FTC_IMAGE_TYPE_HASH( d ) \ 1.716 + (FT_UFast)( FTC_FACE_ID_HASH( (d)->face_id ) ^ \ 1.717 + ( (d)->width << 8 ) ^ (d)->height ^ \ 1.718 + ( (d)->flags << 4 ) ) 1.719 + 1.720 +#endif /* FT_CONFIG_OPTION_OLD_INTERNALS */ 1.721 + 1.722 + 1.723 + /*************************************************************************/ 1.724 + /* */ 1.725 + /* <Type> */ 1.726 + /* FTC_ImageCache */ 1.727 + /* */ 1.728 + /* <Description> */ 1.729 + /* A handle to an glyph image cache object. They are designed to */ 1.730 + /* hold many distinct glyph images while not exceeding a certain */ 1.731 + /* memory threshold. */ 1.732 + /* */ 1.733 + typedef struct FTC_ImageCacheRec_* FTC_ImageCache; 1.734 + 1.735 + 1.736 + /*************************************************************************/ 1.737 + /* */ 1.738 + /* <Function> */ 1.739 + /* FTC_ImageCache_New */ 1.740 + /* */ 1.741 + /* <Description> */ 1.742 + /* Create a new glyph image cache. */ 1.743 + /* */ 1.744 + /* <Input> */ 1.745 + /* manager :: The parent manager for the image cache. */ 1.746 + /* */ 1.747 + /* <Output> */ 1.748 + /* acache :: A handle to the new glyph image cache object. */ 1.749 + /* */ 1.750 + /* <Return> */ 1.751 + /* FreeType error code. 0~means success. */ 1.752 + /* */ 1.753 + FT_EXPORT( FT_Error ) 1.754 + FTC_ImageCache_New( FTC_Manager manager, 1.755 + FTC_ImageCache *acache ); 1.756 + 1.757 + 1.758 + /*************************************************************************/ 1.759 + /* */ 1.760 + /* <Function> */ 1.761 + /* FTC_ImageCache_Lookup */ 1.762 + /* */ 1.763 + /* <Description> */ 1.764 + /* Retrieve a given glyph image from a glyph image cache. */ 1.765 + /* */ 1.766 + /* <Input> */ 1.767 + /* cache :: A handle to the source glyph image cache. */ 1.768 + /* */ 1.769 + /* type :: A pointer to a glyph image type descriptor. */ 1.770 + /* */ 1.771 + /* gindex :: The glyph index to retrieve. */ 1.772 + /* */ 1.773 + /* <Output> */ 1.774 + /* aglyph :: The corresponding @FT_Glyph object. 0~in case of */ 1.775 + /* failure. */ 1.776 + /* */ 1.777 + /* anode :: Used to return the address of of the corresponding cache */ 1.778 + /* node after incrementing its reference count (see note */ 1.779 + /* below). */ 1.780 + /* */ 1.781 + /* <Return> */ 1.782 + /* FreeType error code. 0~means success. */ 1.783 + /* */ 1.784 + /* <Note> */ 1.785 + /* The returned glyph is owned and managed by the glyph image cache. */ 1.786 + /* Never try to transform or discard it manually! You can however */ 1.787 + /* create a copy with @FT_Glyph_Copy and modify the new one. */ 1.788 + /* */ 1.789 + /* If `anode' is _not_ NULL, it receives the address of the cache */ 1.790 + /* node containing the glyph image, after increasing its reference */ 1.791 + /* count. This ensures that the node (as well as the @FT_Glyph) will */ 1.792 + /* always be kept in the cache until you call @FTC_Node_Unref to */ 1.793 + /* `release' it. */ 1.794 + /* */ 1.795 + /* If `anode' is NULL, the cache node is left unchanged, which means */ 1.796 + /* that the @FT_Glyph could be flushed out of the cache on the next */ 1.797 + /* call to one of the caching sub-system APIs. Don't assume that it */ 1.798 + /* is persistent! */ 1.799 + /* */ 1.800 + FT_EXPORT( FT_Error ) 1.801 + FTC_ImageCache_Lookup( FTC_ImageCache cache, 1.802 + FTC_ImageType type, 1.803 + FT_UInt gindex, 1.804 + FT_Glyph *aglyph, 1.805 + FTC_Node *anode ); 1.806 + 1.807 + 1.808 + /*************************************************************************/ 1.809 + /* */ 1.810 + /* <Function> */ 1.811 + /* FTC_ImageCache_LookupScaler */ 1.812 + /* */ 1.813 + /* <Description> */ 1.814 + /* A variant of @FTC_ImageCache_Lookup that uses an @FTC_ScalerRec */ 1.815 + /* to specify the face ID and its size. */ 1.816 + /* */ 1.817 + /* <Input> */ 1.818 + /* cache :: A handle to the source glyph image cache. */ 1.819 + /* */ 1.820 + /* scaler :: A pointer to a scaler descriptor. */ 1.821 + /* */ 1.822 + /* load_flags :: The corresponding load flags. */ 1.823 + /* */ 1.824 + /* gindex :: The glyph index to retrieve. */ 1.825 + /* */ 1.826 + /* <Output> */ 1.827 + /* aglyph :: The corresponding @FT_Glyph object. 0~in case of */ 1.828 + /* failure. */ 1.829 + /* */ 1.830 + /* anode :: Used to return the address of of the corresponding */ 1.831 + /* cache node after incrementing its reference count */ 1.832 + /* (see note below). */ 1.833 + /* */ 1.834 + /* <Return> */ 1.835 + /* FreeType error code. 0~means success. */ 1.836 + /* */ 1.837 + /* <Note> */ 1.838 + /* The returned glyph is owned and managed by the glyph image cache. */ 1.839 + /* Never try to transform or discard it manually! You can however */ 1.840 + /* create a copy with @FT_Glyph_Copy and modify the new one. */ 1.841 + /* */ 1.842 + /* If `anode' is _not_ NULL, it receives the address of the cache */ 1.843 + /* node containing the glyph image, after increasing its reference */ 1.844 + /* count. This ensures that the node (as well as the @FT_Glyph) will */ 1.845 + /* always be kept in the cache until you call @FTC_Node_Unref to */ 1.846 + /* `release' it. */ 1.847 + /* */ 1.848 + /* If `anode' is NULL, the cache node is left unchanged, which means */ 1.849 + /* that the @FT_Glyph could be flushed out of the cache on the next */ 1.850 + /* call to one of the caching sub-system APIs. Don't assume that it */ 1.851 + /* is persistent! */ 1.852 + /* */ 1.853 + /* Calls to @FT_Set_Char_Size and friends have no effect on cached */ 1.854 + /* glyphs; you should always use the FreeType cache API instead. */ 1.855 + /* */ 1.856 + FT_EXPORT( FT_Error ) 1.857 + FTC_ImageCache_LookupScaler( FTC_ImageCache cache, 1.858 + FTC_Scaler scaler, 1.859 + FT_ULong load_flags, 1.860 + FT_UInt gindex, 1.861 + FT_Glyph *aglyph, 1.862 + FTC_Node *anode ); 1.863 + 1.864 + 1.865 + /*************************************************************************/ 1.866 + /* */ 1.867 + /* <Type> */ 1.868 + /* FTC_SBit */ 1.869 + /* */ 1.870 + /* <Description> */ 1.871 + /* A handle to a small bitmap descriptor. See the @FTC_SBitRec */ 1.872 + /* structure for details. */ 1.873 + /* */ 1.874 + typedef struct FTC_SBitRec_* FTC_SBit; 1.875 + 1.876 + 1.877 + /*************************************************************************/ 1.878 + /* */ 1.879 + /* <Struct> */ 1.880 + /* FTC_SBitRec */ 1.881 + /* */ 1.882 + /* <Description> */ 1.883 + /* A very compact structure used to describe a small glyph bitmap. */ 1.884 + /* */ 1.885 + /* <Fields> */ 1.886 + /* width :: The bitmap width in pixels. */ 1.887 + /* */ 1.888 + /* height :: The bitmap height in pixels. */ 1.889 + /* */ 1.890 + /* left :: The horizontal distance from the pen position to the */ 1.891 + /* left bitmap border (a.k.a. `left side bearing', or */ 1.892 + /* `lsb'). */ 1.893 + /* */ 1.894 + /* top :: The vertical distance from the pen position (on the */ 1.895 + /* baseline) to the upper bitmap border (a.k.a. `top */ 1.896 + /* side bearing'). The distance is positive for upwards */ 1.897 + /* y~coordinates. */ 1.898 + /* */ 1.899 + /* format :: The format of the glyph bitmap (monochrome or gray). */ 1.900 + /* */ 1.901 + /* max_grays :: Maximum gray level value (in the range 1 to~255). */ 1.902 + /* */ 1.903 + /* pitch :: The number of bytes per bitmap line. May be positive */ 1.904 + /* or negative. */ 1.905 + /* */ 1.906 + /* xadvance :: The horizontal advance width in pixels. */ 1.907 + /* */ 1.908 + /* yadvance :: The vertical advance height in pixels. */ 1.909 + /* */ 1.910 + /* buffer :: A pointer to the bitmap pixels. */ 1.911 + /* */ 1.912 + typedef struct FTC_SBitRec_ 1.913 + { 1.914 + FT_Byte width; 1.915 + FT_Byte height; 1.916 + FT_Char left; 1.917 + FT_Char top; 1.918 + 1.919 + FT_Byte format; 1.920 + FT_Byte max_grays; 1.921 + FT_Short pitch; 1.922 + FT_Char xadvance; 1.923 + FT_Char yadvance; 1.924 + 1.925 + FT_Byte* buffer; 1.926 + 1.927 + } FTC_SBitRec; 1.928 + 1.929 + 1.930 + /*************************************************************************/ 1.931 + /* */ 1.932 + /* <Type> */ 1.933 + /* FTC_SBitCache */ 1.934 + /* */ 1.935 + /* <Description> */ 1.936 + /* A handle to a small bitmap cache. These are special cache objects */ 1.937 + /* used to store small glyph bitmaps (and anti-aliased pixmaps) in a */ 1.938 + /* much more efficient way than the traditional glyph image cache */ 1.939 + /* implemented by @FTC_ImageCache. */ 1.940 + /* */ 1.941 + typedef struct FTC_SBitCacheRec_* FTC_SBitCache; 1.942 + 1.943 + 1.944 + /*************************************************************************/ 1.945 + /* */ 1.946 + /* <Function> */ 1.947 + /* FTC_SBitCache_New */ 1.948 + /* */ 1.949 + /* <Description> */ 1.950 + /* Create a new cache to store small glyph bitmaps. */ 1.951 + /* */ 1.952 + /* <Input> */ 1.953 + /* manager :: A handle to the source cache manager. */ 1.954 + /* */ 1.955 + /* <Output> */ 1.956 + /* acache :: A handle to the new sbit cache. NULL in case of error. */ 1.957 + /* */ 1.958 + /* <Return> */ 1.959 + /* FreeType error code. 0~means success. */ 1.960 + /* */ 1.961 + FT_EXPORT( FT_Error ) 1.962 + FTC_SBitCache_New( FTC_Manager manager, 1.963 + FTC_SBitCache *acache ); 1.964 + 1.965 + 1.966 + /*************************************************************************/ 1.967 + /* */ 1.968 + /* <Function> */ 1.969 + /* FTC_SBitCache_Lookup */ 1.970 + /* */ 1.971 + /* <Description> */ 1.972 + /* Look up a given small glyph bitmap in a given sbit cache and */ 1.973 + /* `lock' it to prevent its flushing from the cache until needed. */ 1.974 + /* */ 1.975 + /* <Input> */ 1.976 + /* cache :: A handle to the source sbit cache. */ 1.977 + /* */ 1.978 + /* type :: A pointer to the glyph image type descriptor. */ 1.979 + /* */ 1.980 + /* gindex :: The glyph index. */ 1.981 + /* */ 1.982 + /* <Output> */ 1.983 + /* sbit :: A handle to a small bitmap descriptor. */ 1.984 + /* */ 1.985 + /* anode :: Used to return the address of of the corresponding cache */ 1.986 + /* node after incrementing its reference count (see note */ 1.987 + /* below). */ 1.988 + /* */ 1.989 + /* <Return> */ 1.990 + /* FreeType error code. 0~means success. */ 1.991 + /* */ 1.992 + /* <Note> */ 1.993 + /* The small bitmap descriptor and its bit buffer are owned by the */ 1.994 + /* cache and should never be freed by the application. They might */ 1.995 + /* as well disappear from memory on the next cache lookup, so don't */ 1.996 + /* treat them as persistent data. */ 1.997 + /* */ 1.998 + /* The descriptor's `buffer' field is set to~0 to indicate a missing */ 1.999 + /* glyph bitmap. */ 1.1000 + /* */ 1.1001 + /* If `anode' is _not_ NULL, it receives the address of the cache */ 1.1002 + /* node containing the bitmap, after increasing its reference count. */ 1.1003 + /* This ensures that the node (as well as the image) will always be */ 1.1004 + /* kept in the cache until you call @FTC_Node_Unref to `release' it. */ 1.1005 + /* */ 1.1006 + /* If `anode' is NULL, the cache node is left unchanged, which means */ 1.1007 + /* that the bitmap could be flushed out of the cache on the next */ 1.1008 + /* call to one of the caching sub-system APIs. Don't assume that it */ 1.1009 + /* is persistent! */ 1.1010 + /* */ 1.1011 + FT_EXPORT( FT_Error ) 1.1012 + FTC_SBitCache_Lookup( FTC_SBitCache cache, 1.1013 + FTC_ImageType type, 1.1014 + FT_UInt gindex, 1.1015 + FTC_SBit *sbit, 1.1016 + FTC_Node *anode ); 1.1017 + 1.1018 + 1.1019 + /*************************************************************************/ 1.1020 + /* */ 1.1021 + /* <Function> */ 1.1022 + /* FTC_SBitCache_LookupScaler */ 1.1023 + /* */ 1.1024 + /* <Description> */ 1.1025 + /* A variant of @FTC_SBitCache_Lookup that uses an @FTC_ScalerRec */ 1.1026 + /* to specify the face ID and its size. */ 1.1027 + /* */ 1.1028 + /* <Input> */ 1.1029 + /* cache :: A handle to the source sbit cache. */ 1.1030 + /* */ 1.1031 + /* scaler :: A pointer to the scaler descriptor. */ 1.1032 + /* */ 1.1033 + /* load_flags :: The corresponding load flags. */ 1.1034 + /* */ 1.1035 + /* gindex :: The glyph index. */ 1.1036 + /* */ 1.1037 + /* <Output> */ 1.1038 + /* sbit :: A handle to a small bitmap descriptor. */ 1.1039 + /* */ 1.1040 + /* anode :: Used to return the address of of the corresponding */ 1.1041 + /* cache node after incrementing its reference count */ 1.1042 + /* (see note below). */ 1.1043 + /* */ 1.1044 + /* <Return> */ 1.1045 + /* FreeType error code. 0~means success. */ 1.1046 + /* */ 1.1047 + /* <Note> */ 1.1048 + /* The small bitmap descriptor and its bit buffer are owned by the */ 1.1049 + /* cache and should never be freed by the application. They might */ 1.1050 + /* as well disappear from memory on the next cache lookup, so don't */ 1.1051 + /* treat them as persistent data. */ 1.1052 + /* */ 1.1053 + /* The descriptor's `buffer' field is set to~0 to indicate a missing */ 1.1054 + /* glyph bitmap. */ 1.1055 + /* */ 1.1056 + /* If `anode' is _not_ NULL, it receives the address of the cache */ 1.1057 + /* node containing the bitmap, after increasing its reference count. */ 1.1058 + /* This ensures that the node (as well as the image) will always be */ 1.1059 + /* kept in the cache until you call @FTC_Node_Unref to `release' it. */ 1.1060 + /* */ 1.1061 + /* If `anode' is NULL, the cache node is left unchanged, which means */ 1.1062 + /* that the bitmap could be flushed out of the cache on the next */ 1.1063 + /* call to one of the caching sub-system APIs. Don't assume that it */ 1.1064 + /* is persistent! */ 1.1065 + /* */ 1.1066 + FT_EXPORT( FT_Error ) 1.1067 + FTC_SBitCache_LookupScaler( FTC_SBitCache cache, 1.1068 + FTC_Scaler scaler, 1.1069 + FT_ULong load_flags, 1.1070 + FT_UInt gindex, 1.1071 + FTC_SBit *sbit, 1.1072 + FTC_Node *anode ); 1.1073 + 1.1074 + 1.1075 + /* */ 1.1076 + 1.1077 +#ifdef FT_CONFIG_OPTION_OLD_INTERNALS 1.1078 + 1.1079 + /*@***********************************************************************/ 1.1080 + /* */ 1.1081 + /* <Struct> */ 1.1082 + /* FTC_FontRec */ 1.1083 + /* */ 1.1084 + /* <Description> */ 1.1085 + /* A simple structure used to describe a given `font' to the cache */ 1.1086 + /* manager. Note that a `font' is the combination of a given face */ 1.1087 + /* with a given character size. */ 1.1088 + /* */ 1.1089 + /* <Fields> */ 1.1090 + /* face_id :: The ID of the face to use. */ 1.1091 + /* */ 1.1092 + /* pix_width :: The character width in integer pixels. */ 1.1093 + /* */ 1.1094 + /* pix_height :: The character height in integer pixels. */ 1.1095 + /* */ 1.1096 + typedef struct FTC_FontRec_ 1.1097 + { 1.1098 + FTC_FaceID face_id; 1.1099 + FT_UShort pix_width; 1.1100 + FT_UShort pix_height; 1.1101 + 1.1102 + } FTC_FontRec; 1.1103 + 1.1104 + 1.1105 + /* */ 1.1106 + 1.1107 + 1.1108 +#define FTC_FONT_COMPARE( f1, f2 ) \ 1.1109 + ( (f1)->face_id == (f2)->face_id && \ 1.1110 + (f1)->pix_width == (f2)->pix_width && \ 1.1111 + (f1)->pix_height == (f2)->pix_height ) 1.1112 + 1.1113 + /* this macro is incompatible with LLP64, should not be used */ 1.1114 +#define FTC_FONT_HASH( f ) \ 1.1115 + (FT_UInt32)( FTC_FACE_ID_HASH((f)->face_id) ^ \ 1.1116 + ((f)->pix_width << 8) ^ \ 1.1117 + ((f)->pix_height) ) 1.1118 + 1.1119 + typedef FTC_FontRec* FTC_Font; 1.1120 + 1.1121 + 1.1122 + FT_EXPORT( FT_Error ) 1.1123 + FTC_Manager_Lookup_Face( FTC_Manager manager, 1.1124 + FTC_FaceID face_id, 1.1125 + FT_Face *aface ); 1.1126 + 1.1127 + FT_EXPORT( FT_Error ) 1.1128 + FTC_Manager_Lookup_Size( FTC_Manager manager, 1.1129 + FTC_Font font, 1.1130 + FT_Face *aface, 1.1131 + FT_Size *asize ); 1.1132 + 1.1133 +#endif /* FT_CONFIG_OPTION_OLD_INTERNALS */ 1.1134 + 1.1135 + 1.1136 + /* */ 1.1137 + 1.1138 +FT_END_HEADER 1.1139 + 1.1140 +#endif /* __FTCACHE_H__ */ 1.1141 + 1.1142 + 1.1143 +/* END */