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