vrshoot

annotate libs/ft2static/freetype/ftcache.h @ 0:b2f14e535253

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