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