-/***************************************************************************/
-/* */
-/* 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-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 <ft2build.h>
-#include FT_GLYPH_H
+#include <freetype/ftglyph.h>
FT_BEGIN_HEADER
- /*************************************************************************
+ /**************************************************************************
*
- * <Section>
- * cache_subsystem
+ * @section:
+ * cache_subsystem
*
- * <Title>
- * 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
* 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.
*
* 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
* 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
/*************************************************************************/
- /*************************************************************************
+ /**************************************************************************
*
- * @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
* 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
* 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.
*
* 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
/*************************************************************************/
- /*************************************************************************/
- /* */
- /* <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,
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;
} 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 ::
*
* @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.
*
*/
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
*
* @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.
FTC_CMapCache *acache );
- /************************************************************************
+ /**************************************************************************
*
* @function:
* FTC_CMapCache_Lookup
* The character code (in the corresponding charmap).
*
* @return:
- * Glyph index. 0~means `no glyph'.
+ * Glyph index. 0~means 'no glyph'.
*
*/
FT_EXPORT( FT_UInt )
/*************************************************************************/
- /*************************************************************************
+ /**************************************************************************
*
* @struct:
* FTC_ImageTypeRec
} FTC_ImageTypeRec;
- /*************************************************************************
+ /**************************************************************************
*
* @type:
* FTC_ImageType
(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,
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,
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;
} 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,
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,
projects / platform / upstream / freetype2.git / blobdiff