freetype2/include/freetype/ftcache.h

/****************************************************************************
 *
 * 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.
 *
 */


#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 );


  /*************************************************************************
   *
   * @type:
   *   FTC_CMapCache
   *
   * @description:
   *   An opaque handle used to model a charmap cache.  This cache is to
   *   hold character codes -> glyph indices mappings.
   *
   */
  typedef struct FTC_CMapCacheRec_*  FTC_CMapCache;


  /*************************************************************************
   *
   * @function:
   *   FTC_CMapCache_New
   *
   * @description:
   *   Create a new charmap cache.
   *
   * @input:
   *   manager ::
   *     A handle to the cache manager.
   *
   * @output:
   *   acache ::
   *     A new cache handle.  NULL in case of error.
   *
   * @return:
   *   FreeType error code.  0~means success.
   *
   * @note:
   *   Like all other caches, this one will be destroyed with the cache
   *   manager.
   *
   */
  FT_EXPORT( FT_Error )
  FTC_CMapCache_New( FTC_Manager     manager,
                     FTC_CMapCache  *acache );


  /************************************************************************
   *
   * @function:
   *   FTC_CMapCache_Lookup
   *
   * @description:
   *   Translate a character code into a glyph index, using the charmap
   *   cache.
   *
   * @input:
   *   cache ::
   *     A charmap cache handle.
   *
   *   face_id ::
   *     The source face ID.
   *
   *   cmap_index ::
   *     The index of the charmap in the source face.  Any negative value
   *     means to use the cache @FT_Face's default charmap.
   *
   *   char_code ::
   *     The character code (in the corresponding charmap).
   *
   * @return:
   *    Glyph index.  0~means `no glyph'.
   *
   */
  FT_EXPORT( FT_UInt )
  FTC_CMapCache_Lookup( FTC_CMapCache  cache,
                        FTC_FaceID     face_id,
                        FT_Int         cmap_index,
                        FT_UInt32      char_code );


  /*************************************************************************/
  /*************************************************************************/
  /*************************************************************************/
  /*****                                                               *****/
  /*****                       IMAGE CACHE OBJECT                      *****/
  /*****                                                               *****/
  /*************************************************************************/
  /*************************************************************************/
  /*************************************************************************/


  /*************************************************************************
   *
   * @struct:
   *   FTC_ImageTypeRec
   *
   * @description:
   *   A structure used to model the type of images in a glyph cache.
   *
   * @fields:
   *   face_id ::
   *     The face ID.
   *
   *   width ::
   *     The width in pixels.
   *
   *   height ::
   *     The height in pixels.
   *
   *   flags ::
   *     The load flags, as in @FT_Load_Glyph.
   *
   */
  typedef struct  FTC_ImageTypeRec_
  {
    FTC_FaceID  face_id;
    FT_UInt     width;
    FT_UInt     height;
    FT_Int32    flags;

  } FTC_ImageTypeRec;


  /*************************************************************************
   *
   * @type:
   *   FTC_ImageType
   *
   * @description:
   *   A handle to an @FTC_ImageTypeRec structure.
   *
   */
  typedef struct FTC_ImageTypeRec_*  FTC_ImageType;


  /* */


#define FTC_IMAGE_TYPE_COMPARE( d1, d2 )      \
          ( (d1)->face_id == (d2)->face_id && \
            (d1)->width   == (d2)->width   && \
            (d1)->flags   == (d2)->flags   )


  /**************************************************************************
   *
   * @type:
   *   FTC_ImageCache
   *
   * @description:
   *   A handle to a glyph image cache object.  They are designed to
   *   hold many distinct glyph images while not exceeding a certain
   *   memory threshold.
   */
  typedef struct FTC_ImageCacheRec_*  FTC_ImageCache;


  /**************************************************************************
   *
   * @function:
   *   FTC_ImageCache_New
   *
   * @description:
   *   Create a new glyph image cache.
   *
   * @input:
   *   manager ::
   *     The parent manager for the image cache.
   *
   * @output:
   *   acache ::
   *     A handle to the new glyph image cache object.
   *
   * @return:
   *   FreeType error code.  0~means success.
   */
  FT_EXPORT( FT_Error )
  FTC_ImageCache_New( FTC_Manager      manager,
                      FTC_ImageCache  *acache );


  /**************************************************************************
   *
   * @function:
   *   FTC_ImageCache_Lookup
   *
   * @description:
   *   Retrieve a given glyph image from a glyph image cache.
   *
   * @input:
   *   cache ::
   *     A handle to the source glyph image cache.
   *
   *   type ::
   *     A pointer to a glyph image type descriptor.
   *
   *   gindex ::
   *     The glyph index to retrieve.
   *
   * @output:
   *   aglyph ::
   *     The corresponding @FT_Glyph object.  0~in case of
   *     failure.
   *
   *   anode ::
   *     Used to return the address of the corresponding cache
   *     node after incrementing its reference count (see note
   *     below).
   *
   * @return:
   *   FreeType error code.  0~means success.
   *
   * @note:
   *   The returned glyph is owned and managed by the glyph image cache.
   *   Never try to transform or discard it manually!  You can however
   *   create a copy with @FT_Glyph_Copy and modify the new one.
   *
   *   If `anode' is _not_ NULL, it receives the address of the cache
   *   node containing the glyph image, after increasing its reference
   *   count.  This ensures that the node (as well as the @FT_Glyph) will
   *   always be kept in the cache until you call @FTC_Node_Unref to
   *   `release' it.
   *
   *   If `anode' is NULL, the cache node is left unchanged, which means
   *   that the @FT_Glyph could be flushed out of the cache on the next
   *   call to one of the caching sub-system APIs.  Don't assume that it
   *   is persistent!
   */
  FT_EXPORT( FT_Error )
  FTC_ImageCache_Lookup( FTC_ImageCache  cache,
                         FTC_ImageType   type,
                         FT_UInt         gindex,
                         FT_Glyph       *aglyph,
                         FTC_Node       *anode );


  /**************************************************************************
   *
   * @function:
   *   FTC_ImageCache_LookupScaler
   *
   * @description:
   *   A variant of @FTC_ImageCache_Lookup that uses an @FTC_ScalerRec
   *   to specify the face ID and its size.
   *
   * @input:
   *   cache ::
   *     A handle to the source glyph image cache.
   *
   *   scaler ::
   *     A pointer to a scaler descriptor.
   *
   *   load_flags ::
   *     The corresponding load flags.
   *
   *   gindex ::
   *     The glyph index to retrieve.
   *
   * @output:
   *   aglyph ::
   *     The corresponding @FT_Glyph object.  0~in case of
   *     failure.
   *
   *   anode ::
   *     Used to return the address of the corresponding
   *     cache node after incrementing its reference count
   *     (see note below).
   *
   * @return:
   *   FreeType error code.  0~means success.
   *
   * @note:
   *   The returned glyph is owned and managed by the glyph image cache.
   *   Never try to transform or discard it manually!  You can however
   *   create a copy with @FT_Glyph_Copy and modify the new one.
   *
   *   If `anode' is _not_ NULL, it receives the address of the cache
   *   node containing the glyph image, after increasing its reference
   *   count.  This ensures that the node (as well as the @FT_Glyph) will
   *   always be kept in the cache until you call @FTC_Node_Unref to
   *   `release' it.
   *
   *   If `anode' is NULL, the cache node is left unchanged, which means
   *   that the @FT_Glyph could be flushed out of the cache on the next
   *   call to one of the caching sub-system APIs.  Don't assume that it
   *   is persistent!
   *
   *   Calls to @FT_Set_Char_Size and friends have no effect on cached
   *   glyphs; you should always use the FreeType cache API instead.
   */
  FT_EXPORT( FT_Error )
  FTC_ImageCache_LookupScaler( FTC_ImageCache  cache,
                               FTC_Scaler      scaler,
                               FT_ULong        load_flags,
                               FT_UInt         gindex,
                               FT_Glyph       *aglyph,
                               FTC_Node       *anode );


  /**************************************************************************
   *
   * @type:
   *   FTC_SBit
   *
   * @description:
   *   A handle to a small bitmap descriptor.  See the @FTC_SBitRec
   *   structure for details.
   */
  typedef struct FTC_SBitRec_*  FTC_SBit;


  /**************************************************************************
   *
   * @struct:
   *   FTC_SBitRec
   *
   * @description:
   *   A very compact structure used to describe a small glyph bitmap.
   *
   * @fields:
   *   width ::
   *     The bitmap width in pixels.
   *
   *   height ::
   *     The bitmap height in pixels.
   *
   *   left ::
   *     The horizontal distance from the pen position to the
   *     left bitmap border (a.k.a. `left side bearing', or
   *     `lsb').
   *
   *   top ::
   *     The vertical distance from the pen position (on the
   *     baseline) to the upper bitmap border (a.k.a. `top
   *     side bearing').  The distance is positive for upwards
   *     y~coordinates.
   *
   *   format ::
   *     The format of the glyph bitmap (monochrome or gray).
   *
   *   max_grays ::
   *     Maximum gray level value (in the range 1 to~255).
   *
   *   pitch ::
   *     The number of bytes per bitmap line.  May be positive
   *     or negative.
   *
   *   xadvance ::
   *     The horizontal advance width in pixels.
   *
   *   yadvance ::
   *     The vertical advance height in pixels.
   *
   *   buffer ::
   *     A pointer to the bitmap pixels.
   */
  typedef struct  FTC_SBitRec_
  {
    FT_Byte   width;
    FT_Byte   height;
    FT_Char   left;
    FT_Char   top;

    FT_Byte   format;
    FT_Byte   max_grays;
    FT_Short  pitch;
    FT_Char   xadvance;
    FT_Char   yadvance;

    FT_Byte*  buffer;

  } FTC_SBitRec;


  /**************************************************************************
   *
   * @type:
   *   FTC_SBitCache
   *
   * @description:
   *   A handle to a small bitmap cache.  These are special cache objects
   *   used to store small glyph bitmaps (and anti-aliased pixmaps) in a
   *   much more efficient way than the traditional glyph image cache
   *   implemented by @FTC_ImageCache.
   */
  typedef struct FTC_SBitCacheRec_*  FTC_SBitCache;


  /**************************************************************************
   *
   * @function:
   *   FTC_SBitCache_New
   *
   * @description:
   *   Create a new cache to store small glyph bitmaps.
   *
   * @input:
   *   manager ::
   *     A handle to the source cache manager.
   *
   * @output:
   *   acache ::
   *     A handle to the new sbit cache.  NULL in case of error.
   *
   * @return:
   *   FreeType error code.  0~means success.
   */
  FT_EXPORT( FT_Error )
  FTC_SBitCache_New( FTC_Manager     manager,
                     FTC_SBitCache  *acache );


  /**************************************************************************
   *
   * @function:
   *   FTC_SBitCache_Lookup
   *
   * @description:
   *   Look up a given small glyph bitmap in a given sbit cache and
   *   `lock' it to prevent its flushing from the cache until needed.
   *
   * @input:
   *   cache ::
   *     A handle to the source sbit cache.
   *
   *   type ::
   *     A pointer to the glyph image type descriptor.
   *
   *   gindex ::
   *     The glyph index.
   *
   * @output:
   *   sbit ::
   *     A handle to a small bitmap descriptor.
   *
   *   anode ::
   *     Used to return the address of the corresponding cache
   *     node after incrementing its reference count (see note
   *     below).
   *
   * @return:
   *   FreeType error code.  0~means success.
   *
   * @note:
   *   The small bitmap descriptor and its bit buffer are owned by the
   *   cache and should never be freed by the application.  They might
   *   as well disappear from memory on the next cache lookup, so don't
   *   treat them as persistent data.
   *
   *   The descriptor's `buffer' field is set to~0 to indicate a missing
   *   glyph bitmap.
   *
   *   If `anode' is _not_ NULL, it receives the address of the cache
   *   node containing the bitmap, after increasing its reference count.
   *   This ensures that the node (as well as the image) will always be
   *   kept in the cache until you call @FTC_Node_Unref to `release' it.
   *
   *   If `anode' is NULL, the cache node is left unchanged, which means
   *   that the bitmap could be flushed out of the cache on the next
   *   call to one of the caching sub-system APIs.  Don't assume that it
   *   is persistent!
   */
  FT_EXPORT( FT_Error )
  FTC_SBitCache_Lookup( FTC_SBitCache    cache,
                        FTC_ImageType    type,
                        FT_UInt          gindex,
                        FTC_SBit        *sbit,
                        FTC_Node        *anode );


  /**************************************************************************
   *
   * @function:
   *   FTC_SBitCache_LookupScaler
   *
   * @description:
   *   A variant of @FTC_SBitCache_Lookup that uses an @FTC_ScalerRec
   *   to specify the face ID and its size.
   *
   * @input:
   *   cache ::
   *     A handle to the source sbit cache.
   *
   *   scaler ::
   *     A pointer to the scaler descriptor.
   *
   *   load_flags ::
   *     The corresponding load flags.
   *
   *   gindex ::
   *     The glyph index.
   *
   * @output:
   *   sbit ::
   *     A handle to a small bitmap descriptor.
   *
   *   anode ::
   *     Used to return the address of the corresponding
   *     cache node after incrementing its reference count
   *     (see note below).
   *
   * @return:
   *   FreeType error code.  0~means success.
   *
   * @note:
   *   The small bitmap descriptor and its bit buffer are owned by the
   *   cache and should never be freed by the application.  They might
   *   as well disappear from memory on the next cache lookup, so don't
   *   treat them as persistent data.
   *
   *   The descriptor's `buffer' field is set to~0 to indicate a missing
   *   glyph bitmap.
   *
   *   If `anode' is _not_ NULL, it receives the address of the cache
   *   node containing the bitmap, after increasing its reference count.
   *   This ensures that the node (as well as the image) will always be
   *   kept in the cache until you call @FTC_Node_Unref to `release' it.
   *
   *   If `anode' is NULL, the cache node is left unchanged, which means
   *   that the bitmap could be flushed out of the cache on the next
   *   call to one of the caching sub-system APIs.  Don't assume that it
   *   is persistent!
   */
  FT_EXPORT( FT_Error )
  FTC_SBitCache_LookupScaler( FTC_SBitCache  cache,
                              FTC_Scaler     scaler,
                              FT_ULong       load_flags,
                              FT_UInt        gindex,
                              FTC_SBit      *sbit,
                              FTC_Node      *anode );

  /* */


FT_END_HEADER

#endif /* FTCACHE_H_ */


/* END */