From 58f56950848bae9c90da3873090c7698e0128b12 Mon Sep 17 00:00:00 2001 From: Liang Qi Date: Wed, 14 Aug 2019 11:13:36 +0200 Subject: Update bundled Freetype to 2.10.1 [ChangeLog][Freetype] Upgraded bundled Freetype version to 2.10.1. Fixes: QTBUG-77466 Change-Id: I1de8b8b03e0ffd0b17eeafff1017df7c638c9279 Reviewed-by: Eskil Abrahamsen Blomfeldt --- src/3rdparty/freetype/include/freetype/ftcache.h | 1190 +++++++++++----------- 1 file changed, 618 insertions(+), 572 deletions(-) (limited to 'src/3rdparty/freetype/include/freetype/ftcache.h') diff --git a/src/3rdparty/freetype/include/freetype/ftcache.h b/src/3rdparty/freetype/include/freetype/ftcache.h index 52d5f00e06..0d589d0b34 100644 --- a/src/3rdparty/freetype/include/freetype/ftcache.h +++ b/src/3rdparty/freetype/include/freetype/ftcache.h @@ -1,19 +1,19 @@ -/***************************************************************************/ -/* */ -/* ftcache.h */ -/* */ -/* FreeType Cache subsystem (specification). */ -/* */ -/* Copyright 1996-2018 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. */ -/* */ -/***************************************************************************/ +/**************************************************************************** + * + * ftcache.h + * + * FreeType Cache subsystem (specification). + * + * Copyright (C) 1996-2019 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_ @@ -27,24 +27,24 @@ FT_BEGIN_HEADER - /************************************************************************* + /************************************************************************** * - *
- * cache_subsystem + * @section: + * cache_subsystem * - * - * Cache Sub-System + * @title: + * Cache Sub-System * - * <Abstract> - * How to cache face, size, and glyph data with FreeType~2. + * @abstract: + * How to cache face, size, and glyph data with FreeType~2. * - * <Description> + * @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. + * 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 @@ -59,7 +59,7 @@ FT_BEGIN_HEADER * 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 + * 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. * @@ -69,14 +69,14 @@ FT_BEGIN_HEADER * 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 + * **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. + * 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 @@ -91,16 +91,16 @@ FT_BEGIN_HEADER * 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). + * 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> + * @order: * FTC_Manager * FTC_FaceID * FTC_Face_Requester @@ -142,19 +142,20 @@ FT_BEGIN_HEADER /*************************************************************************/ - /************************************************************************* + /************************************************************************** * - * @type: FTC_FaceID + * @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. + * 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. + * 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 @@ -165,13 +166,13 @@ FT_BEGIN_HEADER * 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. + * Failure to do so will result in incorrect behaviour or even memory + * leaks and crashes. */ typedef FT_Pointer FTC_FaceID; - /************************************************************************ + /************************************************************************** * * @functype: * FTC_Face_Requester @@ -181,7 +182,7 @@ FT_BEGIN_HEADER * the cache manager to translate a given @FTC_FaceID into a new valid * @FT_Face object, on demand. * - * <Input> + * @input: * face_id :: * The face ID to resolve. * @@ -191,15 +192,15 @@ FT_BEGIN_HEADER * req_data :: * Application-provided request data (see note below). * - * <Output> + * @output: * aface :: * A new @FT_Face handle. * - * <Return> + * @return: * FreeType error code. 0~means success. * - * <Note> - * The third parameter `req_data' is the same as the one passed by the + * @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 @@ -226,84 +227,90 @@ FT_BEGIN_HEADER /*************************************************************************/ - /*************************************************************************/ - /* */ - /* <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. */ - /* */ + /************************************************************************** + * + * @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. */ - /* */ + /************************************************************************** + * + * @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. */ - /* */ + /************************************************************************** + * + * @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, @@ -314,114 +321,124 @@ FT_BEGIN_HEADER 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. */ - /* */ + /************************************************************************** + * + * @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. */ - /* */ + /************************************************************************** + * + * @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. */ - /* */ + /************************************************************************** + * + * @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. */ - /* */ + /************************************************************************** + * + * @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; @@ -434,89 +451,93 @@ FT_BEGIN_HEADER } FTC_ScalerRec; - /*************************************************************************/ - /* */ - /* <Struct> */ - /* FTC_Scaler */ - /* */ - /* <Description> */ - /* A handle to an @FTC_ScalerRec structure. */ - /* */ + /************************************************************************** + * + * @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. */ - /* */ + /************************************************************************** + * + * @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. */ - /* */ + /************************************************************************** + * + * @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. + * 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 :: @@ -527,11 +548,11 @@ FT_BEGIN_HEADER * * @note: * This function flushes all nodes from the cache corresponding to this - * `face_id', with the exception of nodes with a non-null reference + * `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 + * 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. * */ @@ -540,20 +561,20 @@ FT_BEGIN_HEADER 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. + * 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 @@ -567,7 +588,7 @@ FT_BEGIN_HEADER * * @output: * acache :: - * A new cache handle. NULL in case of error. + * A new cache handle. `NULL` in case of error. * * @return: * FreeType error code. 0~means success. @@ -582,7 +603,7 @@ FT_BEGIN_HEADER FTC_CMapCache *acache ); - /************************************************************************ + /************************************************************************** * * @function: * FTC_CMapCache_Lookup @@ -606,7 +627,7 @@ FT_BEGIN_HEADER * The character code (in the corresponding charmap). * * @return: - * Glyph index. 0~means `no glyph'. + * Glyph index. 0~means 'no glyph'. * */ FT_EXPORT( FT_UInt ) @@ -627,7 +648,7 @@ FT_BEGIN_HEADER /*************************************************************************/ - /************************************************************************* + /************************************************************************** * * @struct: * FTC_ImageTypeRec @@ -659,7 +680,7 @@ FT_BEGIN_HEADER } FTC_ImageTypeRec; - /************************************************************************* + /************************************************************************** * * @type: * FTC_ImageType @@ -680,83 +701,87 @@ FT_BEGIN_HEADER (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. */ - /* */ + /************************************************************************** + * + * @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. */ - /* */ + /************************************************************************** + * + * @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! */ - /* */ + /************************************************************************** + * + * @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, @@ -765,54 +790,57 @@ FT_BEGIN_HEADER 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. */ - /* */ + /************************************************************************** + * + * @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, @@ -822,53 +850,60 @@ FT_BEGIN_HEADER FTC_Node *anode ); - /*************************************************************************/ - /* */ - /* <Type> */ - /* FTC_SBit */ - /* */ - /* <Description> */ - /* A handle to a small bitmap descriptor. See the @FTC_SBitRec */ - /* structure for details. */ - /* */ + /************************************************************************** + * + * @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. */ - /* */ + /************************************************************************** + * + * @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; @@ -887,87 +922,93 @@ FT_BEGIN_HEADER } 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. */ - /* */ + /************************************************************************** + * + * @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. */ - /* */ + /************************************************************************** + * + * @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! */ - /* */ + /************************************************************************** + * + * @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, @@ -976,53 +1017,58 @@ FT_BEGIN_HEADER 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! */ - /* */ + /************************************************************************** + * + * @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, -- cgit v1.2.3