/**************************************************************************** * * ftcache.h * * FreeType Cache subsystem (specification). * * Copyright (C) 1996-2020 by * David Turner, Robert Wilhelm, and Werner Lemberg. * * This file is part of the FreeType project, and may only be used, * modified, and distributed under the terms of the FreeType project * license, LICENSE.TXT. By continuing to use, modify, or distribute * this file you indicate that you have read the license and * understand and accept it fully. * */ #ifndef FTCACHE_H_ #define FTCACHE_H_ #include <freetype/ftglyph.h> FT_BEGIN_HEADER /************************************************************************** * * @section: * cache_subsystem * * @title: * Cache Sub-System * * @abstract: * How to cache face, size, and glyph data with FreeType~2. * * @description: * This section describes the FreeType~2 cache sub-system, which is used * to limit the number of concurrently opened @FT_Face and @FT_Size * objects, as well as caching information like character maps and glyph * images while limiting their maximum memory usage. * * Note that all types and functions begin with the `FTC_` prefix. * * The cache is highly portable and thus doesn't know anything about the * fonts installed on your system, or how to access them. This implies * the following scheme: * * First, available or installed font faces are uniquely identified by * @FTC_FaceID values, provided to the cache by the client. Note that * the cache only stores and compares these values, and doesn't try to * interpret them in any way. * * Second, the cache calls, only when needed, a client-provided function * to convert an @FTC_FaceID into a new @FT_Face object. The latter is * then completely managed by the cache, including its termination * through @FT_Done_Face. To monitor termination of face objects, the * finalizer callback in the `generic` field of the @FT_Face object can * be used, which might also be used to store the @FTC_FaceID of the * face. * * Clients are free to map face IDs to anything else. The most simple * usage is to associate them to a (pathname,face_index) pair that is * used to call @FT_New_Face. However, more complex schemes are also * possible. * * Note that for the cache to work correctly, the face ID values must be * **persistent**, which means that the contents they point to should not * change at runtime, or that their value should not become invalid. * * If this is unavoidable (e.g., when a font is uninstalled at runtime), * you should call @FTC_Manager_RemoveFaceID as soon as possible, to let * the cache get rid of any references to the old @FTC_FaceID it may keep * internally. Failure to do so will lead to incorrect behaviour or even * crashes. * * To use the cache, start with calling @FTC_Manager_New to create a new * @FTC_Manager object, which models a single cache instance. You can * then look up @FT_Face and @FT_Size objects with * @FTC_Manager_LookupFace and @FTC_Manager_LookupSize, respectively. * * If you want to use the charmap caching, call @FTC_CMapCache_New, then * later use @FTC_CMapCache_Lookup to perform the equivalent of * @FT_Get_Char_Index, only much faster. * * If you want to use the @FT_Glyph caching, call @FTC_ImageCache, then * later use @FTC_ImageCache_Lookup to retrieve the corresponding * @FT_Glyph objects from the cache. * * If you need lots of small bitmaps, it is much more memory efficient to * call @FTC_SBitCache_New followed by @FTC_SBitCache_Lookup. This * returns @FTC_SBitRec structures, which are used to store small bitmaps * directly. (A small bitmap is one whose metrics and dimensions all fit * into 8-bit integers). * * We hope to also provide a kerning cache in the near future. * * * @order: * FTC_Manager * FTC_FaceID * FTC_Face_Requester * * FTC_Manager_New * FTC_Manager_Reset * FTC_Manager_Done * FTC_Manager_LookupFace * FTC_Manager_LookupSize * FTC_Manager_RemoveFaceID * * FTC_Node * FTC_Node_Unref * * FTC_ImageCache * FTC_ImageCache_New * FTC_ImageCache_Lookup * * FTC_SBit * FTC_SBitCache * FTC_SBitCache_New * FTC_SBitCache_Lookup * * FTC_CMapCache * FTC_CMapCache_New * FTC_CMapCache_Lookup * *************************************************************************/ /*************************************************************************/ /*************************************************************************/ /*************************************************************************/ /***** *****/ /***** BASIC TYPE DEFINITIONS *****/ /***** *****/ /*************************************************************************/ /*************************************************************************/ /*************************************************************************/ /************************************************************************** * * @type: * FTC_FaceID * * @description: * An opaque pointer type that is used to identity face objects. The * contents of such objects is application-dependent. * * These pointers are typically used to point to a user-defined structure * containing a font file path, and face index. * * @note: * Never use `NULL` as a valid @FTC_FaceID. * * Face IDs are passed by the client to the cache manager that calls, * when needed, the @FTC_Face_Requester to translate them into new * @FT_Face objects. * * If the content of a given face ID changes at runtime, or if the value * becomes invalid (e.g., when uninstalling a font), you should * immediately call @FTC_Manager_RemoveFaceID before any other cache * function. * * Failure to do so will result in incorrect behaviour or even memory * leaks and crashes. */ typedef FT_Pointer FTC_FaceID; /************************************************************************** * * @functype: * FTC_Face_Requester * * @description: * A callback function provided by client applications. It is used by * the cache manager to translate a given @FTC_FaceID into a new valid * @FT_Face object, on demand. * * @input: * face_id :: * The face ID to resolve. * * library :: * A handle to a FreeType library object. * * req_data :: * Application-provided request data (see note below). * * @output: * aface :: * A new @FT_Face handle. * * @return: * FreeType error code. 0~means success. * * @note: * The third parameter `req_data` is the same as the one passed by the * client when @FTC_Manager_New is called. * * The face requester should not perform funny things on the returned * face object, like creating a new @FT_Size for it, or setting a * transformation through @FT_Set_Transform! */ typedef FT_Error (*FTC_Face_Requester)( FTC_FaceID face_id, FT_Library library, FT_Pointer req_data, FT_Face* aface ); /* */ /*************************************************************************/ /*************************************************************************/ /*************************************************************************/ /***** *****/ /***** CACHE MANAGER OBJECT *****/ /***** *****/ /*************************************************************************/ /*************************************************************************/ /*************************************************************************/ /************************************************************************** * * @type: * FTC_Manager * * @description: * This object corresponds to one instance of the cache-subsystem. It is * used to cache one or more @FT_Face objects, along with corresponding * @FT_Size objects. * * The manager intentionally limits the total number of opened @FT_Face * and @FT_Size objects to control memory usage. See the `max_faces` and * `max_sizes` parameters of @FTC_Manager_New. * * The manager is also used to cache 'nodes' of various types while * limiting their total memory usage. * * All limitations are enforced by keeping lists of managed objects in * most-recently-used order, and flushing old nodes to make room for new * ones. */ typedef struct FTC_ManagerRec_* FTC_Manager; /************************************************************************** * * @type: * FTC_Node * * @description: * An opaque handle to a cache node object. Each cache node is * reference-counted. A node with a count of~0 might be flushed out of a * full cache whenever a lookup request is performed. * * If you look up nodes, you have the ability to 'acquire' them, i.e., to * increment their reference count. This will prevent the node from * being flushed out of the cache until you explicitly 'release' it (see * @FTC_Node_Unref). * * See also @FTC_SBitCache_Lookup and @FTC_ImageCache_Lookup. */ typedef struct FTC_NodeRec_* FTC_Node; /************************************************************************** * * @function: * FTC_Manager_New * * @description: * Create a new cache manager. * * @input: * library :: * The parent FreeType library handle to use. * * max_faces :: * Maximum number of opened @FT_Face objects managed by this cache * instance. Use~0 for defaults. * * max_sizes :: * Maximum number of opened @FT_Size objects managed by this cache * instance. Use~0 for defaults. * * max_bytes :: * Maximum number of bytes to use for cached data nodes. Use~0 for * defaults. Note that this value does not account for managed * @FT_Face and @FT_Size objects. * * requester :: * An application-provided callback used to translate face IDs into * real @FT_Face objects. * * req_data :: * A generic pointer that is passed to the requester each time it is * called (see @FTC_Face_Requester). * * @output: * amanager :: * A handle to a new manager object. 0~in case of failure. * * @return: * FreeType error code. 0~means success. */ FT_EXPORT( FT_Error ) FTC_Manager_New( FT_Library library, FT_UInt max_faces, FT_UInt max_sizes, FT_ULong max_bytes, FTC_Face_Requester requester, FT_Pointer req_data, FTC_Manager *amanager ); /************************************************************************** * * @function: * FTC_Manager_Reset * * @description: * Empty a given cache manager. This simply gets rid of all the * currently cached @FT_Face and @FT_Size objects within the manager. * * @inout: * manager :: * A handle to the manager. */ FT_EXPORT( void ) FTC_Manager_Reset( FTC_Manager manager ); /************************************************************************** * * @function: * FTC_Manager_Done * * @description: * Destroy a given manager after emptying it. * * @input: * manager :: * A handle to the target cache manager object. */ FT_EXPORT( void ) FTC_Manager_Done( FTC_Manager manager ); /************************************************************************** * * @function: * FTC_Manager_LookupFace * * @description: * Retrieve the @FT_Face object that corresponds to a given face ID * through a cache manager. * * @input: * manager :: * A handle to the cache manager. * * face_id :: * The ID of the face object. * * @output: * aface :: * A handle to the face object. * * @return: * FreeType error code. 0~means success. * * @note: * The returned @FT_Face object is always owned by the manager. You * should never try to discard it yourself. * * The @FT_Face object doesn't necessarily have a current size object * (i.e., face->size can be~0). If you need a specific 'font size', use * @FTC_Manager_LookupSize instead. * * Never change the face's transformation matrix (i.e., never call the * @FT_Set_Transform function) on a returned face! If you need to * transform glyphs, do it yourself after glyph loading. * * When you perform a lookup, out-of-memory errors are detected _within_ * the lookup and force incremental flushes of the cache until enough * memory is released for the lookup to succeed. * * If a lookup fails with `FT_Err_Out_Of_Memory` the cache has already * been completely flushed, and still no memory was available for the * operation. */ FT_EXPORT( FT_Error ) FTC_Manager_LookupFace( FTC_Manager manager, FTC_FaceID face_id, FT_Face *aface ); /************************************************************************** * * @struct: * FTC_ScalerRec * * @description: * A structure used to describe a given character size in either pixels * or points to the cache manager. See @FTC_Manager_LookupSize. * * @fields: * face_id :: * The source face ID. * * width :: * The character width. * * height :: * The character height. * * pixel :: * A Boolean. If 1, the `width` and `height` fields are interpreted as * integer pixel character sizes. Otherwise, they are expressed as * 1/64th of points. * * x_res :: * Only used when `pixel` is value~0 to indicate the horizontal * resolution in dpi. * * y_res :: * Only used when `pixel` is value~0 to indicate the vertical * resolution in dpi. * * @note: * This type is mainly used to retrieve @FT_Size objects through the * cache manager. */ typedef struct FTC_ScalerRec_ { FTC_FaceID face_id; FT_UInt width; FT_UInt height; FT_Int pixel; FT_UInt x_res; FT_UInt y_res; } FTC_ScalerRec; /************************************************************************** * * @struct: * FTC_Scaler * * @description: * A handle to an @FTC_ScalerRec structure. */ typedef struct FTC_ScalerRec_* FTC_Scaler; /************************************************************************** * * @function: * FTC_Manager_LookupSize * * @description: * Retrieve the @FT_Size object that corresponds to a given * @FTC_ScalerRec pointer through a cache manager. * * @input: * manager :: * A handle to the cache manager. * * scaler :: * A scaler handle. * * @output: * asize :: * A handle to the size object. * * @return: * FreeType error code. 0~means success. * * @note: * The returned @FT_Size object is always owned by the manager. You * should never try to discard it by yourself. * * You can access the parent @FT_Face object simply as `size->face` if * you need it. Note that this object is also owned by the manager. * * @note: * When you perform a lookup, out-of-memory errors are detected _within_ * the lookup and force incremental flushes of the cache until enough * memory is released for the lookup to succeed. * * If a lookup fails with `FT_Err_Out_Of_Memory` the cache has already * been completely flushed, and still no memory is available for the * operation. */ FT_EXPORT( FT_Error ) FTC_Manager_LookupSize( FTC_Manager manager, FTC_Scaler scaler, FT_Size *asize ); /************************************************************************** * * @function: * FTC_Node_Unref * * @description: * Decrement a cache node's internal reference count. When the count * reaches 0, it is not destroyed but becomes eligible for subsequent * cache flushes. * * @input: * node :: * The cache node handle. * * manager :: * The cache manager handle. */ FT_EXPORT( void ) FTC_Node_Unref( FTC_Node node, FTC_Manager manager ); /************************************************************************** * * @function: * FTC_Manager_RemoveFaceID * * @description: * A special function used to indicate to the cache manager that a given * @FTC_FaceID is no longer valid, either because its content changed, or * because it was deallocated or uninstalled. * * @input: * manager :: * The cache manager handle. * * face_id :: * The @FTC_FaceID to be removed. * * @note: * This function flushes all nodes from the cache corresponding to this * `face_id`, with the exception of nodes with a non-null reference * count. * * Such nodes are however modified internally so as to never appear in * later lookups with the same `face_id` value, and to be immediately * destroyed when released by all their users. * */ FT_EXPORT( void ) FTC_Manager_RemoveFaceID( FTC_Manager manager, FTC_FaceID face_id ); /************************************************************************** * * @type: * FTC_CMapCache * * @description: * An opaque handle used to model a charmap cache. This cache is to hold * character codes -> glyph indices mappings. * */ typedef struct FTC_CMapCacheRec_* FTC_CMapCache; /************************************************************************** * * @function: * FTC_CMapCache_New * * @description: * Create a new charmap cache. * * @input: * manager :: * A handle to the cache manager. * * @output: * acache :: * A new cache handle. `NULL` in case of error. * * @return: * FreeType error code. 0~means success. * * @note: * Like all other caches, this one will be destroyed with the cache * manager. * */ FT_EXPORT( FT_Error ) FTC_CMapCache_New( FTC_Manager manager, FTC_CMapCache *acache ); /************************************************************************** * * @function: * FTC_CMapCache_Lookup * * @description: * Translate a character code into a glyph index, using the charmap * cache. * * @input: * cache :: * A charmap cache handle. * * face_id :: * The source face ID. * * cmap_index :: * The index of the charmap in the source face. Any negative value * means to use the cache @FT_Face's default charmap. * * char_code :: * The character code (in the corresponding charmap). * * @return: * Glyph index. 0~means 'no glyph'. * */ FT_EXPORT( FT_UInt ) FTC_CMapCache_Lookup( FTC_CMapCache cache, FTC_FaceID face_id, FT_Int cmap_index, FT_UInt32 char_code ); /*************************************************************************/ /*************************************************************************/ /*************************************************************************/ /***** *****/ /***** IMAGE CACHE OBJECT *****/ /***** *****/ /*************************************************************************/ /*************************************************************************/ /*************************************************************************/ /************************************************************************** * * @struct: * FTC_ImageTypeRec * * @description: * A structure used to model the type of images in a glyph cache. * * @fields: * face_id :: * The face ID. * * width :: * The width in pixels. * * height :: * The height in pixels. * * flags :: * The load flags, as in @FT_Load_Glyph. * */ typedef struct FTC_ImageTypeRec_ { FTC_FaceID face_id; FT_UInt width; FT_UInt height; FT_Int32 flags; } FTC_ImageTypeRec; /************************************************************************** * * @type: * FTC_ImageType * * @description: * A handle to an @FTC_ImageTypeRec structure. * */ typedef struct FTC_ImageTypeRec_* FTC_ImageType; /* */ #define FTC_IMAGE_TYPE_COMPARE( d1, d2 ) \ ( (d1)->face_id == (d2)->face_id && \ (d1)->width == (d2)->width && \ (d1)->flags == (d2)->flags ) /************************************************************************** * * @type: * FTC_ImageCache * * @description: * A handle to a glyph image cache object. They are designed to hold * many distinct glyph images while not exceeding a certain memory * threshold. */ typedef struct FTC_ImageCacheRec_* FTC_ImageCache; /************************************************************************** * * @function: * FTC_ImageCache_New * * @description: * Create a new glyph image cache. * * @input: * manager :: * The parent manager for the image cache. * * @output: * acache :: * A handle to the new glyph image cache object. * * @return: * FreeType error code. 0~means success. */ FT_EXPORT( FT_Error ) FTC_ImageCache_New( FTC_Manager manager, FTC_ImageCache *acache ); /************************************************************************** * * @function: * FTC_ImageCache_Lookup * * @description: * Retrieve a given glyph image from a glyph image cache. * * @input: * cache :: * A handle to the source glyph image cache. * * type :: * A pointer to a glyph image type descriptor. * * gindex :: * The glyph index to retrieve. * * @output: * aglyph :: * The corresponding @FT_Glyph object. 0~in case of failure. * * anode :: * Used to return the address of the corresponding cache node after * incrementing its reference count (see note below). * * @return: * FreeType error code. 0~means success. * * @note: * The returned glyph is owned and managed by the glyph image cache. * Never try to transform or discard it manually! You can however create * a copy with @FT_Glyph_Copy and modify the new one. * * If `anode` is _not_ `NULL`, it receives the address of the cache node * containing the glyph image, after increasing its reference count. * This ensures that the node (as well as the @FT_Glyph) will always be * kept in the cache until you call @FTC_Node_Unref to 'release' it. * * If `anode` is `NULL`, the cache node is left unchanged, which means * that the @FT_Glyph could be flushed out of the cache on the next call * to one of the caching sub-system APIs. Don't assume that it is * persistent! */ FT_EXPORT( FT_Error ) FTC_ImageCache_Lookup( FTC_ImageCache cache, FTC_ImageType type, FT_UInt gindex, FT_Glyph *aglyph, FTC_Node *anode ); /************************************************************************** * * @function: * FTC_ImageCache_LookupScaler * * @description: * A variant of @FTC_ImageCache_Lookup that uses an @FTC_ScalerRec to * specify the face ID and its size. * * @input: * cache :: * A handle to the source glyph image cache. * * scaler :: * A pointer to a scaler descriptor. * * load_flags :: * The corresponding load flags. * * gindex :: * The glyph index to retrieve. * * @output: * aglyph :: * The corresponding @FT_Glyph object. 0~in case of failure. * * anode :: * Used to return the address of the corresponding cache node after * incrementing its reference count (see note below). * * @return: * FreeType error code. 0~means success. * * @note: * The returned glyph is owned and managed by the glyph image cache. * Never try to transform or discard it manually! You can however create * a copy with @FT_Glyph_Copy and modify the new one. * * If `anode` is _not_ `NULL`, it receives the address of the cache node * containing the glyph image, after increasing its reference count. * This ensures that the node (as well as the @FT_Glyph) will always be * kept in the cache until you call @FTC_Node_Unref to 'release' it. * * If `anode` is `NULL`, the cache node is left unchanged, which means * that the @FT_Glyph could be flushed out of the cache on the next call * to one of the caching sub-system APIs. Don't assume that it is * persistent! * * Calls to @FT_Set_Char_Size and friends have no effect on cached * glyphs; you should always use the FreeType cache API instead. */ FT_EXPORT( FT_Error ) FTC_ImageCache_LookupScaler( FTC_ImageCache cache, FTC_Scaler scaler, FT_ULong load_flags, FT_UInt gindex, FT_Glyph *aglyph, FTC_Node *anode ); /************************************************************************** * * @type: * FTC_SBit * * @description: * A handle to a small bitmap descriptor. See the @FTC_SBitRec structure * for details. */ typedef struct FTC_SBitRec_* FTC_SBit; /************************************************************************** * * @struct: * FTC_SBitRec * * @description: * A very compact structure used to describe a small glyph bitmap. * * @fields: * width :: * The bitmap width in pixels. * * height :: * The bitmap height in pixels. * * left :: * The horizontal distance from the pen position to the left bitmap * border (a.k.a. 'left side bearing', or 'lsb'). * * top :: * The vertical distance from the pen position (on the baseline) to the * upper bitmap border (a.k.a. 'top side bearing'). The distance is * positive for upwards y~coordinates. * * format :: * The format of the glyph bitmap (monochrome or gray). * * max_grays :: * Maximum gray level value (in the range 1 to~255). * * pitch :: * The number of bytes per bitmap line. May be positive or negative. * * xadvance :: * The horizontal advance width in pixels. * * yadvance :: * The vertical advance height in pixels. * * buffer :: * A pointer to the bitmap pixels. */ typedef struct FTC_SBitRec_ { FT_Byte width; FT_Byte height; FT_Char left; FT_Char top; FT_Byte format; FT_Byte max_grays; FT_Short pitch; FT_Char xadvance; FT_Char yadvance; FT_Byte* buffer; } FTC_SBitRec; /************************************************************************** * * @type: * FTC_SBitCache * * @description: * A handle to a small bitmap cache. These are special cache objects * used to store small glyph bitmaps (and anti-aliased pixmaps) in a much * more efficient way than the traditional glyph image cache implemented * by @FTC_ImageCache. */ typedef struct FTC_SBitCacheRec_* FTC_SBitCache; /************************************************************************** * * @function: * FTC_SBitCache_New * * @description: * Create a new cache to store small glyph bitmaps. * * @input: * manager :: * A handle to the source cache manager. * * @output: * acache :: * A handle to the new sbit cache. `NULL` in case of error. * * @return: * FreeType error code. 0~means success. */ FT_EXPORT( FT_Error ) FTC_SBitCache_New( FTC_Manager manager, FTC_SBitCache *acache ); /************************************************************************** * * @function: * FTC_SBitCache_Lookup * * @description: * Look up a given small glyph bitmap in a given sbit cache and 'lock' it * to prevent its flushing from the cache until needed. * * @input: * cache :: * A handle to the source sbit cache. * * type :: * A pointer to the glyph image type descriptor. * * gindex :: * The glyph index. * * @output: * sbit :: * A handle to a small bitmap descriptor. * * anode :: * Used to return the address of the corresponding cache node after * incrementing its reference count (see note below). * * @return: * FreeType error code. 0~means success. * * @note: * The small bitmap descriptor and its bit buffer are owned by the cache * and should never be freed by the application. They might as well * disappear from memory on the next cache lookup, so don't treat them as * persistent data. * * The descriptor's `buffer` field is set to~0 to indicate a missing * glyph bitmap. * * If `anode` is _not_ `NULL`, it receives the address of the cache node * containing the bitmap, after increasing its reference count. This * ensures that the node (as well as the image) will always be kept in * the cache until you call @FTC_Node_Unref to 'release' it. * * If `anode` is `NULL`, the cache node is left unchanged, which means * that the bitmap could be flushed out of the cache on the next call to * one of the caching sub-system APIs. Don't assume that it is * persistent! */ FT_EXPORT( FT_Error ) FTC_SBitCache_Lookup( FTC_SBitCache cache, FTC_ImageType type, FT_UInt gindex, FTC_SBit *sbit, FTC_Node *anode ); /************************************************************************** * * @function: * FTC_SBitCache_LookupScaler * * @description: * A variant of @FTC_SBitCache_Lookup that uses an @FTC_ScalerRec to * specify the face ID and its size. * * @input: * cache :: * A handle to the source sbit cache. * * scaler :: * A pointer to the scaler descriptor. * * load_flags :: * The corresponding load flags. * * gindex :: * The glyph index. * * @output: * sbit :: * A handle to a small bitmap descriptor. * * anode :: * Used to return the address of the corresponding cache node after * incrementing its reference count (see note below). * * @return: * FreeType error code. 0~means success. * * @note: * The small bitmap descriptor and its bit buffer are owned by the cache * and should never be freed by the application. They might as well * disappear from memory on the next cache lookup, so don't treat them as * persistent data. * * The descriptor's `buffer` field is set to~0 to indicate a missing * glyph bitmap. * * If `anode` is _not_ `NULL`, it receives the address of the cache node * containing the bitmap, after increasing its reference count. This * ensures that the node (as well as the image) will always be kept in * the cache until you call @FTC_Node_Unref to 'release' it. * * If `anode` is `NULL`, the cache node is left unchanged, which means * that the bitmap could be flushed out of the cache on the next call to * one of the caching sub-system APIs. Don't assume that it is * persistent! */ FT_EXPORT( FT_Error ) FTC_SBitCache_LookupScaler( FTC_SBitCache cache, FTC_Scaler scaler, FT_ULong load_flags, FT_UInt gindex, FTC_SBit *sbit, FTC_Node *anode ); /* */ FT_END_HEADER #endif /* FTCACHE_H_ */ /* END */ SIMPAN PERUBAHAN