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