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