开通博客赚积分
发布资源赚积分
分类

源码开发语言/平台
当前位置：首页 > 源码/资料 > 游戏 > 其他游戏 > 查看源码
ftcache.h
资源名称：wow-313-source.rar　[点击查看]
上传用户：yisoukefu
上传日期：2020-08-09
资源大小：39506k
文件大小：58k
源码类别：

其他游戏

开发平台：

Visual C++

ftcache.h：源码内容
  1. /***************************************************************************/
  2. /*                                                                         */
  3. /*  ftcache.h                                                              */
  4. /*                                                                         */
  5. /*    FreeType Cache subsystem (specification).                            */
  6. /*                                                                         */
  7. /*  Copyright 1996-2001, 2002, 2003, 2004, 2005, 2006, 2007 by             */
  8. /*  David Turner, Robert Wilhelm, and Werner Lemberg.                      */
  9. /*                                                                         */
  10. /*  This file is part of the FreeType project, and may only be used,       */
  11. /*  modified, and distributed under the terms of the FreeType project      */
  12. /*  license, LICENSE.TXT.  By continuing to use, modify, or distribute     */
  13. /*  this file you indicate that you have read the license and              */
  14. /*  understand and accept it fully.                                        */
  15. /*                                                                         */
  16. /***************************************************************************/
  19. #ifndef __FTCACHE_H__
  20. #define __FTCACHE_H__
  23. #include <ft2build.h>
  24. #include FT_GLYPH_H
  27. FT_BEGIN_HEADER
  30.   /*************************************************************************
  31.    *
  32.    * <Section>
  33.    *    cache_subsystem
  34.    *
  35.    * <Title>
  36.    *    Cache Sub-System
  37.    *
  38.    * <Abstract>
  39.    *    How to cache face, size, and glyph data with FreeType 2.
  40.    *
  41.    * <Description>
  42.    *   This section describes the FreeType 2 cache sub-system, which is used
  43.    *   to limit the number of concurrently opened @FT_Face and @FT_Size
  44.    *   objects, as well as caching information like character maps and glyph
  45.    *   images while limiting their maximum memory usage.
  46.    *
  47.    *   Note that all types and functions begin with the `FTC_' prefix.
  48.    *
  49.    *   The cache is highly portable and thus doesn't know anything about the
  50.    *   fonts installed on your system, or how to access them.  This implies
  51.    *   the following scheme:
  52.    *
  53.    *   First, available or installed font faces are uniquely identified by
  54.    *   @FTC_FaceID values, provided to the cache by the client.  Note that
  55.    *   the cache only stores and compares these values, and doesn't try to
  56.    *   interpret them in any way.
  57.    *
  58.    *   Second, the cache calls, only when needed, a client-provided function
  59.    *   to convert a @FTC_FaceID into a new @FT_Face object.  The latter is
  60.    *   then completely managed by the cache, including its termination
  61.    *   through @FT_Done_Face.
  62.    *
  63.    *   Clients are free to map face IDs to anything else.  The most simple
  64.    *   usage is to associate them to a (pathname,face_index) pair that is
  65.    *   used to call @FT_New_Face.  However, more complex schemes are also
  66.    *   possible.
  67.    *
  68.    *   Note that for the cache to work correctly, the face ID values must be
  69.    *   *persistent*, which means that the contents they point to should not
  70.    *   change at runtime, or that their value should not become invalid.
  71.    *
  72.    *   If this is unavoidable (e.g., when a font is uninstalled at runtime),
  73.    *   you should call @FTC_Manager_RemoveFaceID as soon as possible, to let
  74.    *   the cache get rid of any references to the old @FTC_FaceID it may
  75.    *   keep internally.  Failure to do so will lead to incorrect behaviour
  76.    *   or even crashes.
  77.    *
  78.    *   To use the cache, start with calling @FTC_Manager_New to create a new
  79.    *   @FTC_Manager object, which models a single cache instance.  You can
  80.    *   then look up @FT_Face and @FT_Size objects with
  81.    *   @FTC_Manager_LookupFace and @FTC_Manager_LookupSize, respectively.
  82.    *
  83.    *   If you want to use the charmap caching, call @FTC_CMapCache_New, then
  84.    *   later use @FTC_CMapCache_Lookup to perform the equivalent of
  85.    *   @FT_Get_Char_Index, only much faster.
  86.    *
  87.    *   If you want to use the @FT_Glyph caching, call @FTC_ImageCache, then
  88.    *   later use @FTC_ImageCache_Lookup to retrieve the corresponding
  89.    *   @FT_Glyph objects from the cache.
  90.    *
  91.    *   If you need lots of small bitmaps, it is much more memory efficient
  92.    *   to call @FTC_SBitCache_New followed by @FTC_SBitCache_Lookup.  This
  93.    *   returns @FTC_SBitRec structures, which are used to store small
  94.    *   bitmaps directly.  (A small bitmap is one whose metrics and
  95.    *   dimensions all fit into 8-bit integers).
  96.    *
  97.    *   We hope to also provide a kerning cache in the near future.
  98.    *
  99.    *
  100.    * <Order>
  101.    *   FTC_Manager
  102.    *   FTC_FaceID
  103.    *   FTC_Face_Requester
  104.    *
  105.    *   FTC_Manager_New
  106.    *   FTC_Manager_Reset
  107.    *   FTC_Manager_Done
  108.    *   FTC_Manager_LookupFace
  109.    *   FTC_Manager_LookupSize
  110.    *   FTC_Manager_RemoveFaceID
  111.    *
  112.    *   FTC_Node
  113.    *   FTC_Node_Unref
  114.    *
  115.    *   FTC_ImageCache
  116.    *   FTC_ImageCache_New
  117.    *   FTC_ImageCache_Lookup
  118.    *
  119.    *   FTC_SBit
  120.    *   FTC_SBitCache
  121.    *   FTC_SBitCache_New
  122.    *   FTC_SBitCache_Lookup
  123.    *
  124.    *   FTC_CMapCache
  125.    *   FTC_CMapCache_New
  126.    *   FTC_CMapCache_Lookup
  127.    *
  128.    *************************************************************************/
  131.   /*************************************************************************/
  132.   /*************************************************************************/
  133.   /*************************************************************************/
  134.   /*****                                                               *****/
  135.   /*****                    BASIC TYPE DEFINITIONS                     *****/
  136.   /*****                                                               *****/
  137.   /*************************************************************************/
  138.   /*************************************************************************/
  139.   /*************************************************************************/
  142.   /*************************************************************************
  143.    *
  144.    * @type: FTC_FaceID
  145.    *
  146.    * @description:
  147.    *   An opaque pointer type that is used to identity face objects.  The
  148.    *   contents of such objects is application-dependent.
  149.    *
  150.    *   These pointers are typically used to point to a user-defined
  151.    *   structure containing a font file path, and face index.
  152.    *
  153.    * @note:
  154.    *   Never use NULL as a valid @FTC_FaceID.
  155.    *
  156.    *   Face IDs are passed by the client to the cache manager, which calls,
  157.    *   when needed, the @FTC_Face_Requester to translate them into new
  158.    *   @FT_Face objects.
  159.    *
  160.    *   If the content of a given face ID changes at runtime, or if the value
  161.    *   becomes invalid (e.g., when uninstalling a font), you should
  162.    *   immediately call @FTC_Manager_RemoveFaceID before any other cache
  163.    *   function.
  164.    *
  165.    *   Failure to do so will result in incorrect behaviour or even
  166.    *   memory leaks and crashes.
  167.    */
  168.   typedef struct FTC_FaceIDRec_*  FTC_FaceID;
  171.   /************************************************************************
  172.    *
  173.    * @functype:
  174.    *   FTC_Face_Requester
  175.    *
  176.    * @description:
  177.    *   A callback function provided by client applications.  It is used by
  178.    *   the cache manager to translate a given @FTC_FaceID into a new valid
  179.    *   @FT_Face object, on demand.
  180.    *
  181.    * <Input>
  182.    *   face_id ::
  183.    *     The face ID to resolve.
  184.    *
  185.    *   library ::
  186.    *     A handle to a FreeType library object.
  187.    *
  188.    *   req_data ::
  189.    *     Application-provided request data (see note below).
  190.    *
  191.    * <Output>
  192.    *   aface ::
  193.    *     A new @FT_Face handle.
  194.    *
  195.    * <Return>
  196.    *   FreeType error code.  0 means success.
  197.    *
  198.    * <Note>
  199.    *   The third parameter `req_data' is the same as the one passed by the
  200.    *   client when @FTC_Manager_New is called.
  201.    *
  202.    *   The face requester should not perform funny things on the returned
  203.    *   face object, like creating a new @FT_Size for it, or setting a
  204.    *   transformation through @FT_Set_Transform!
  205.    */
  206.   typedef FT_Error
  207.   (*FTC_Face_Requester)( FTC_FaceID  face_id,
  208.                          FT_Library  library,
  209.                          FT_Pointer  request_data,
  210.                          FT_Face*    aface );
  212.  /* */
  214. #define FT_POINTER_TO_ULONG( p )  ( (FT_ULong)(FT_Pointer)(p) )
  216. #define FTC_FACE_ID_HASH( i )                                
  217.           ((FT_UInt32)(( FT_POINTER_TO_ULONG( i ) >> 3 ) ^   
  218.                        ( FT_POINTER_TO_ULONG( i ) << 7 ) ) )
  221.   /*************************************************************************/
  222.   /*************************************************************************/
  223.   /*************************************************************************/
  224.   /*****                                                               *****/
  225.   /*****                      CACHE MANAGER OBJECT                     *****/
  226.   /*****                                                               *****/
  227.   /*************************************************************************/
  228.   /*************************************************************************/
  229.   /*************************************************************************/
  232.   /*************************************************************************/
  233.   /*                                                                       */
  234.   /* <Type>                                                                */
  235.   /*    FTC_Manager                                                        */
  236.   /*                                                                       */
  237.   /* <Description>                                                         */
  238.   /*    This object corresponds to one instance of the cache-subsystem.    */
  239.   /*    It is used to cache one or more @FT_Face objects, along with       */
  240.   /*    corresponding @FT_Size objects.                                    */
  241.   /*                                                                       */
  242.   /*    The manager intentionally limits the total number of opened        */
  243.   /*    @FT_Face and @FT_Size objects to control memory usage.  See the    */
  244.   /*    `max_faces' and `max_sizes' parameters of @FTC_Manager_New.        */
  245.   /*                                                                       */
  246.   /*    The manager is also used to cache `nodes' of various types while   */
  247.   /*    limiting their total memory usage.                                 */
  248.   /*                                                                       */
  249.   /*    All limitations are enforced by keeping lists of managed objects   */
  250.   /*    in most-recently-used order, and flushing old nodes to make room   */
  251.   /*    for new ones.                                                      */
  252.   /*                                                                       */
  253.   typedef struct FTC_ManagerRec_*  FTC_Manager;
  256.   /*************************************************************************/
  257.   /*                                                                       */
  258.   /* <Type>                                                                */
  259.   /*    FTC_Node                                                           */
  260.   /*                                                                       */
  261.   /* <Description>                                                         */
  262.   /*    An opaque handle to a cache node object.  Each cache node is       */
  263.   /*    reference-counted.  A node with a count of 0 might be flushed      */
  264.   /*    out of a full cache whenever a lookup request is performed.        */
  265.   /*                                                                       */
  266.   /*    If you lookup nodes, you have the ability to `acquire' them, i.e., */
  267.   /*    to increment their reference count.  This will prevent the node    */
  268.   /*    from being flushed out of the cache until you explicitly `release' */
  269.   /*    it (see @FTC_Node_Unref).                                          */
  270.   /*                                                                       */
  271.   /*    See also @FTC_SBitCache_Lookup and @FTC_ImageCache_Lookup.         */
  272.   /*                                                                       */
  273.   typedef struct FTC_NodeRec_*  FTC_Node;
  276.   /*************************************************************************/
  277.   /*                                                                       */
  278.   /* <Function>                                                            */
  279.   /*    FTC_Manager_New                                                    */
  280.   /*                                                                       */
  281.   /* <Description>                                                         */
  282.   /*    Creates a new cache manager.                                       */
  283.   /*                                                                       */
  284.   /* <Input>                                                               */
  285.   /*    library   :: The parent FreeType library handle to use.            */
  286.   /*                                                                       */
  287.   /*    max_faces :: Maximum number of opened @FT_Face objects managed by  */
  288.   /*                 this cache instance.  Use 0 for defaults.             */
  289.   /*                                                                       */
  290.   /*    max_sizes :: Maximum number of opened @FT_Size objects managed by  */
  291.   /*                 this cache instance.  Use 0 for defaults.             */
  292.   /*                                                                       */
  293.   /*    max_bytes :: Maximum number of bytes to use for cached data nodes. */
  294.   /*                 Use 0 for defaults.  Note that this value does not    */
  295.   /*                 account for managed @FT_Face and @FT_Size objects.    */
  296.   /*                                                                       */
  297.   /*    requester :: An application-provided callback used to translate    */
  298.   /*                 face IDs into real @FT_Face objects.                  */
  299.   /*                                                                       */
  300.   /*    req_data  :: A generic pointer that is passed to the requester     */
  301.   /*                 each time it is called (see @FTC_Face_Requester).     */
  302.   /*                                                                       */
  303.   /* <Output>                                                              */
  304.   /*    amanager  :: A handle to a new manager object.  0 in case of       */
  305.   /*                 failure.                                              */
  306.   /*                                                                       */
  307.   /* <Return>                                                              */
  308.   /*    FreeType error code.  0 means success.                             */
  309.   /*                                                                       */
  310.   FT_EXPORT( FT_Error )
  311.   FTC_Manager_New( FT_Library          library,
  312.                    FT_UInt             max_faces,
  313.                    FT_UInt             max_sizes,
  314.                    FT_ULong            max_bytes,
  315.                    FTC_Face_Requester  requester,
  316.                    FT_Pointer          req_data,
  317.                    FTC_Manager        *amanager );
  320.   /*************************************************************************/
  321.   /*                                                                       */
  322.   /* <Function>                                                            */
  323.   /*    FTC_Manager_Reset                                                  */
  324.   /*                                                                       */
  325.   /* <Description>                                                         */
  326.   /*    Empties a given cache manager.  This simply gets rid of all the    */
  327.   /*    currently cached @FT_Face and @FT_Size objects within the manager. */
  328.   /*                                                                       */
  329.   /* <InOut>                                                               */
  330.   /*    manager :: A handle to the manager.                                */
  331.   /*                                                                       */
  332.   FT_EXPORT( void )
  333.   FTC_Manager_Reset( FTC_Manager  manager );
  336.   /*************************************************************************/
  337.   /*                                                                       */
  338.   /* <Function>                                                            */
  339.   /*    FTC_Manager_Done                                                   */
  340.   /*                                                                       */
  341.   /* <Description>                                                         */
  342.   /*    Destroys a given manager after emptying it.                        */
  343.   /*                                                                       */
  344.   /* <Input>                                                               */
  345.   /*    manager :: A handle to the target cache manager object.            */
  346.   /*                                                                       */
  347.   FT_EXPORT( void )
  348.   FTC_Manager_Done( FTC_Manager  manager );
  351.   /*************************************************************************/
  352.   /*                                                                       */
  353.   /* <Function>                                                            */
  354.   /*    FTC_Manager_LookupFace                                             */
  355.   /*                                                                       */
  356.   /* <Description>                                                         */
  357.   /*    Retrieves the @FT_Face object that corresponds to a given face ID  */
  358.   /*    through a cache manager.                                           */
  359.   /*                                                                       */
  360.   /* <Input>                                                               */
  361.   /*    manager :: A handle to the cache manager.                          */
  362.   /*                                                                       */
  363.   /*    face_id :: The ID of the face object.                              */
  364.   /*                                                                       */
  365.   /* <Output>                                                              */
  366.   /*    aface   :: A handle to the face object.                            */
  367.   /*                                                                       */
  368.   /* <Return>                                                              */
  369.   /*    FreeType error code.  0 means success.                             */
  370.   /*                                                                       */
  371.   /* <Note>                                                                */
  372.   /*    The returned @FT_Face object is always owned by the manager.  You  */
  373.   /*    should never try to discard it yourself.                           */
  374.   /*                                                                       */
  375.   /*    The @FT_Face object doesn't necessarily have a current size object */
  376.   /*    (i.e., face->size can be 0).  If you need a specific `font size',  */
  377.   /*    use @FTC_Manager_LookupSize instead.                               */
  378.   /*                                                                       */
  379.   /*    Never change the face's transformation matrix (i.e., never call    */
  380.   /*    the @FT_Set_Transform function) on a returned face!  If you need   */
  381.   /*    to transform glyphs, do it yourself after glyph loading.           */
  382.   /*                                                                       */
  383.   /*    When you perform a lookup, out-of-memory errors are detected       */
  384.   /*    _within_ the lookup and force incremental flushes of the cache     */
  385.   /*    until enough memory is released for the lookup to succeed.         */
  386.   /*                                                                       */
  387.   /*    If a lookup fails with `FT_Err_Out_Of_Memory' the cache has        */
  388.   /*    already been completely flushed, and still no memory was available */
  389.   /*    for the operation.                                                 */
  390.   /*                                                                       */
  391.   FT_EXPORT( FT_Error )
  392.   FTC_Manager_LookupFace( FTC_Manager  manager,
  393.                           FTC_FaceID   face_id,
  394.                           FT_Face     *aface );
  397.   /*************************************************************************/
  398.   /*                                                                       */
  399.   /* <Struct>                                                              */
  400.   /*    FTC_ScalerRec                                                      */
  401.   /*                                                                       */
  402.   /* <Description>                                                         */
  403.   /*    A structure used to describe a given character size in either      */
  404.   /*    pixels or points to the cache manager.  See                        */
  405.   /*    @FTC_Manager_LookupSize.                                           */
  406.   /*                                                                       */
  407.   /* <Fields>                                                              */
  408.   /*    face_id :: The source face ID.                                     */
  409.   /*                                                                       */
  410.   /*    width   :: The character width.                                    */
  411.   /*                                                                       */
  412.   /*    height  :: The character height.                                   */
  413.   /*                                                                       */
  414.   /*    pixel   :: A Boolean.  If 1, the `width' and `height' fields are   */
  415.   /*               interpreted as integer pixel character sizes.           */
  416.   /*               Otherwise, they are expressed as 1/64th of points.      */
  417.   /*                                                                       */
  418.   /*    x_res   :: Only used when `pixel' is value 0 to indicate the       */
  419.   /*               horizontal resolution in dpi.                           */
  420.   /*                                                                       */
  421.   /*    y_res   :: Only used when `pixel' is value 0 to indicate the       */
  422.   /*               vertical resolution in dpi.                             */
  423.   /*                                                                       */
  424.   /* <Note>                                                                */
  425.   /*    This type is mainly used to retrieve @FT_Size objects through the  */
  426.   /*    cache manager.                                                     */
  427.   /*                                                                       */
  428.   typedef struct  FTC_ScalerRec_
  429.   {
  430.     FTC_FaceID  face_id;
  431.     FT_UInt     width;
  432.     FT_UInt     height;
  433.     FT_Int      pixel;
  434.     FT_UInt     x_res;
  435.     FT_UInt     y_res;
  437.   } FTC_ScalerRec, *FTC_Scaler;
  440.   /*************************************************************************/
  441.   /*                                                                       */
  442.   /* <Function>                                                            */
  443.   /*    FTC_Manager_LookupSize                                             */
  444.   /*                                                                       */
  445.   /* <Description>                                                         */
  446.   /*    Retrieve the @FT_Size object that corresponds to a given           */
  447.   /*    @FTC_ScalerRec pointer through a cache manager.                    */
  448.   /*                                                                       */
  449.   /* <Input>                                                               */
  450.   /*    manager :: A handle to the cache manager.                          */
  451.   /*                                                                       */
  452.   /*    scaler  :: A scaler handle.                                        */
  453.   /*                                                                       */
  454.   /* <Output>                                                              */
  455.   /*    asize   :: A handle to the size object.                            */
  456.   /*                                                                       */
  457.   /* <Return>                                                              */
  458.   /*    FreeType error code.  0 means success.                             */
  459.   /*                                                                       */
  460.   /* <Note>                                                                */
  461.   /*    The returned @FT_Size object is always owned by the manager.  You  */
  462.   /*    should never try to discard it by yourself.                        */
  463.   /*                                                                       */
  464.   /*    You can access the parent @FT_Face object simply as `size->face'   */
  465.   /*    if you need it.  Note that this object is also owned by the        */
  466.   /*    manager.                                                           */
  467.   /*                                                                       */
  468.   /* <Note>                                                                */
  469.   /*    When you perform a lookup, out-of-memory errors are detected       */
  470.   /*    _within_ the lookup and force incremental flushes of the cache     */
  471.   /*    until enough memory is released for the lookup to succeed.         */
  472.   /*                                                                       */
  473.   /*    If a lookup fails with `FT_Err_Out_Of_Memory' the cache has        */
  474.   /*    already been completely flushed, and still no memory is available  */
  475.   /*    for the operation.                                                 */
  476.   /*                                                                       */
  477.   FT_EXPORT( FT_Error )
  478.   FTC_Manager_LookupSize( FTC_Manager  manager,
  479.                           FTC_Scaler   scaler,
  480.                           FT_Size     *asize );
  483.   /*************************************************************************/
  484.   /*                                                                       */
  485.   /* <Function>                                                            */
  486.   /*    FTC_Node_Unref                                                     */
  487.   /*                                                                       */
  488.   /* <Description>                                                         */
  489.   /*    Decrement a cache node's internal reference count.  When the count */
  490.   /*    reaches 0, it is not destroyed but becomes eligible for subsequent */
  491.   /*    cache flushes.                                                     */
  492.   /*                                                                       */
  493.   /* <Input>                                                               */
  494.   /*    node    :: The cache node handle.                                  */
  495.   /*                                                                       */
  496.   /*    manager :: The cache manager handle.                               */
  497.   /*                                                                       */
  498.   FT_EXPORT( void )
  499.   FTC_Node_Unref( FTC_Node     node,
  500.                   FTC_Manager  manager );
  503.   /*************************************************************************
  504.    *
  505.    * @function:
  506.    *   FTC_Manager_RemoveFaceID
  507.    *
  508.    * @description:
  509.    *   A special function used to indicate to the cache manager that
  510.    *   a given @FTC_FaceID is no longer valid, either because its
  511.    *   content changed, or because it was deallocated or uninstalled.
  512.    *
  513.    * @input:
  514.    *   manager ::
  515.    *     The cache manager handle.
  516.    *
  517.    *   face_id ::
  518.    *     The @FTC_FaceID to be removed.
  519.    *
  520.    * @note:
  521.    *   This function flushes all nodes from the cache corresponding to this
  522.    *   `face_id', with the exception of nodes with a non-null reference
  523.    *   count.
  524.    *
  525.    *   Such nodes are however modified internally so as to never appear
  526.    *   in later lookups with the same `face_id' value, and to be immediately
  527.    *   destroyed when released by all their users.
  528.    *
  529.    */
  530.   FT_EXPORT( void )
  531.   FTC_Manager_RemoveFaceID( FTC_Manager  manager,
  532.                             FTC_FaceID   face_id );
  535.   /*************************************************************************/
  536.   /*                                                                       */
  537.   /* <Section>                                                             */
  538.   /*    cache_subsystem                                                    */
  539.   /*                                                                       */
  540.   /*************************************************************************/
  542.   /*************************************************************************
  543.    *
  544.    * @type:
  545.    *   FTC_CMapCache
  546.    *
  547.    * @description:
  548.    *   An opaque handle used to model a charmap cache.  This cache is to
  549.    *   hold character codes -> glyph indices mappings.
  550.    *
  551.    */
  552.   typedef struct FTC_CMapCacheRec_*  FTC_CMapCache;
  555.   /*************************************************************************
  556.    *
  557.    * @function:
  558.    *   FTC_CMapCache_New
  559.    *
  560.    * @description:
  561.    *   Create a new charmap cache.
  562.    *
  563.    * @input:
  564.    *   manager ::
  565.    *     A handle to the cache manager.
  566.    *
  567.    * @output:
  568.    *   acache ::
  569.    *     A new cache handle.  NULL in case of error.
  570.    *
  571.    * @return:
  572.    *   FreeType error code.  0 means success.
  573.    *
  574.    * @note:
  575.    *   Like all other caches, this one will be destroyed with the cache
  576.    *   manager.
  577.    *
  578.    */
  579.   FT_EXPORT( FT_Error )
  580.   FTC_CMapCache_New( FTC_Manager     manager,
  581.                      FTC_CMapCache  *acache );
  584.   /************************************************************************
  585.    *
  586.    * @function:
  587.    *   FTC_CMapCache_Lookup
  588.    *
  589.    * @description:
  590.    *   Translate a character code into a glyph index, using the charmap
  591.    *   cache.
  592.    *
  593.    * @input:
  594.    *   cache ::
  595.    *     A charmap cache handle.
  596.    *
  597.    *   face_id ::
  598.    *     The source face ID.
  599.    *
  600.    *   cmap_index ::
  601.    *     The index of the charmap in the source face.
  602.    *
  603.    *   char_code ::
  604.    *     The character code (in the corresponding charmap).
  605.    *
  606.    * @return:
  607.    *    Glyph index.  0 means `no glyph'.
  608.    *
  609.    */
  610.   FT_EXPORT( FT_UInt )
  611.   FTC_CMapCache_Lookup( FTC_CMapCache  cache,
  612.                         FTC_FaceID     face_id,
  613.                         FT_Int         cmap_index,
  614.                         FT_UInt32      char_code );
  617.   /*************************************************************************/
  618.   /*                                                                       */
  619.   /* <Section>                                                             */
  620.   /*    cache_subsystem                                                    */
  621.   /*                                                                       */
  622.   /*************************************************************************/
  625.   /*************************************************************************/
  626.   /*************************************************************************/
  627.   /*************************************************************************/
  628.   /*****                                                               *****/
  629.   /*****                       IMAGE CACHE OBJECT                      *****/
  630.   /*****                                                               *****/
  631.   /*************************************************************************/
  632.   /*************************************************************************/
  633.   /*************************************************************************/
  636.   /*************************************************************************
  637.    *
  638.    * @struct:
  639.    *   FTC_ImageTypeRec
  640.    *
  641.    * @description:
  642.    *   A structure used to model the type of images in a glyph cache.
  643.    *
  644.    * @fields:
  645.    *   face_id ::
  646.    *     The face ID.
  647.    *
  648.    *   width ::
  649.    *     The width in pixels.
  650.    *
  651.    *   height ::
  652.    *     The height in pixels.
  653.    *
  654.    *   flags ::
  655.    *     The load flags, as in @FT_Load_Glyph.
  656.    *
  657.    */
  658.   typedef struct  FTC_ImageTypeRec_
  659.   {
  660.     FTC_FaceID  face_id;
  661.     FT_Int      width;
  662.     FT_Int      height;
  663.     FT_Int32    flags;
  665.   } FTC_ImageTypeRec;
  668.   /*************************************************************************
  669.    *
  670.    * @type:
  671.    *   FTC_ImageType
  672.    *
  673.    * @description:
  674.    *   A handle to an @FTC_ImageTypeRec structure.
  675.    *
  676.    */
  677.   typedef struct FTC_ImageTypeRec_*  FTC_ImageType;
  680.   /* */
  683. #define FTC_IMAGE_TYPE_COMPARE( d1, d2 )      
  684.           ( (d1)->face_id == (d2)->face_id && 
  685.             (d1)->width   == (d2)->width   && 
  686.             (d1)->flags   == (d2)->flags   )
  688. #define FTC_IMAGE_TYPE_HASH( d )                          
  689.           (FT_UFast)( FTC_FACE_ID_HASH( (d)->face_id )  ^ 
  690.                       ( (d)->width << 8 ) ^ (d)->height ^ 
  691.                       ( (d)->flags << 4 )               )
  694.   /*************************************************************************/
  695.   /*                                                                       */
  696.   /* <Type>                                                                */
  697.   /*    FTC_ImageCache                                                     */
  698.   /*                                                                       */
  699.   /* <Description>                                                         */
  700.   /*    A handle to an glyph image cache object.  They are designed to     */
  701.   /*    hold many distinct glyph images while not exceeding a certain      */
  702.   /*    memory threshold.                                                  */
  703.   /*                                                                       */
  704.   typedef struct FTC_ImageCacheRec_*  FTC_ImageCache;
  707.   /*************************************************************************/
  708.   /*                                                                       */
  709.   /* <Function>                                                            */
  710.   /*    FTC_ImageCache_New                                                 */
  711.   /*                                                                       */
  712.   /* <Description>                                                         */
  713.   /*    Creates a new glyph image cache.                                   */
  714.   /*                                                                       */
  715.   /* <Input>                                                               */
  716.   /*    manager :: The parent manager for the image cache.                 */
  717.   /*                                                                       */
  718.   /* <Output>                                                              */
  719.   /*    acache  :: A handle to the new glyph image cache object.           */
  720.   /*                                                                       */
  721.   /* <Return>                                                              */
  722.   /*    FreeType error code.  0 means success.                             */
  723.   /*                                                                       */
  724.   FT_EXPORT( FT_Error )
  725.   FTC_ImageCache_New( FTC_Manager      manager,
  726.                       FTC_ImageCache  *acache );
  729.   /*************************************************************************/
  730.   /*                                                                       */
  731.   /* <Function>                                                            */
  732.   /*    FTC_ImageCache_Lookup                                              */
  733.   /*                                                                       */
  734.   /* <Description>                                                         */
  735.   /*    Retrieves a given glyph image from a glyph image cache.            */
  736.   /*                                                                       */
  737.   /* <Input>                                                               */
  738.   /*    cache  :: A handle to the source glyph image cache.                */
  739.   /*                                                                       */
  740.   /*    type   :: A pointer to a glyph image type descriptor.              */
  741.   /*                                                                       */
  742.   /*    gindex :: The glyph index to retrieve.                             */
  743.   /*                                                                       */
  744.   /* <Output>                                                              */
  745.   /*    aglyph :: The corresponding @FT_Glyph object.  0 in case of        */
  746.   /*              failure.                                                 */
  747.   /*                                                                       */
  748.   /*    anode  :: Used to return the address of of the corresponding cache */
  749.   /*              node after incrementing its reference count (see note    */
  750.   /*              below).                                                  */
  751.   /*                                                                       */
  752.   /* <Return>                                                              */
  753.   /*    FreeType error code.  0 means success.                             */
  754.   /*                                                                       */
  755.   /* <Note>                                                                */
  756.   /*    The returned glyph is owned and managed by the glyph image cache.  */
  757.   /*    Never try to transform or discard it manually!  You can however    */
  758.   /*    create a copy with @FT_Glyph_Copy and modify the new one.          */
  759.   /*                                                                       */
  760.   /*    If `anode' is _not_ NULL, it receives the address of the cache     */
  761.   /*    node containing the glyph image, after increasing its reference    */
  762.   /*    count.  This ensures that the node (as well as the @FT_Glyph) will */
  763.   /*    always be kept in the cache until you call @FTC_Node_Unref to      */
  764.   /*    `release' it.                                                      */
  765.   /*                                                                       */
  766.   /*    If `anode' is NULL, the cache node is left unchanged, which means  */
  767.   /*    that the @FT_Glyph could be flushed out of the cache on the next   */
  768.   /*    call to one of the caching sub-system APIs.  Don't assume that it  */
  769.   /*    is persistent!                                                     */
  770.   /*                                                                       */
  771.   FT_EXPORT( FT_Error )
  772.   FTC_ImageCache_Lookup( FTC_ImageCache  cache,
  773.                          FTC_ImageType   type,
  774.                          FT_UInt         gindex,
  775.                          FT_Glyph       *aglyph,
  776.                          FTC_Node       *anode );
  779.   /*************************************************************************/
  780.   /*                                                                       */
  781.   /* <Function>                                                            */
  782.   /*    FTC_ImageCache_LookupScaler                                        */
  783.   /*                                                                       */
  784.   /* <Description>                                                         */
  785.   /*    A variant of @FTC_ImageCache_Lookup that uses an @FTC_ScalerRec    */
  786.   /*    to specify the face ID and its size.                               */
  787.   /*                                                                       */
  788.   /* <Input>                                                               */
  789.   /*    cache      :: A handle to the source glyph image cache.            */
  790.   /*                                                                       */
  791.   /*    scaler     :: A pointer to a scaler descriptor.                    */
  792.   /*                                                                       */
  793.   /*    load_flags :: The corresponding load flags.                        */
  794.   /*                                                                       */
  795.   /*    gindex     :: The glyph index to retrieve.                         */
  796.   /*                                                                       */
  797.   /* <Output>                                                              */
  798.   /*    aglyph     :: The corresponding @FT_Glyph object.  0 in case of    */
  799.   /*                  failure.                                             */
  800.   /*                                                                       */
  801.   /*    anode      :: Used to return the address of of the corresponding   */
  802.   /*                  cache node after incrementing its reference count    */
  803.   /*                  (see note below).                                    */
  804.   /*                                                                       */
  805.   /* <Return>                                                              */
  806.   /*    FreeType error code.  0 means success.                             */
  807.   /*                                                                       */
  808.   /* <Note>                                                                */
  809.   /*    The returned glyph is owned and managed by the glyph image cache.  */
  810.   /*    Never try to transform or discard it manually!  You can however    */
  811.   /*    create a copy with @FT_Glyph_Copy and modify the new one.          */
  812.   /*                                                                       */
  813.   /*    If `anode' is _not_ NULL, it receives the address of the cache     */
  814.   /*    node containing the glyph image, after increasing its reference    */
  815.   /*    count.  This ensures that the node (as well as the @FT_Glyph) will */
  816.   /*    always be kept in the cache until you call @FTC_Node_Unref to      */
  817.   /*    `release' it.                                                      */
  818.   /*                                                                       */
  819.   /*    If `anode' is NULL, the cache node is left unchanged, which means  */
  820.   /*    that the @FT_Glyph could be flushed out of the cache on the next   */
  821.   /*    call to one of the caching sub-system APIs.  Don't assume that it  */
  822.   /*    is persistent!                                                     */
  823.   /*                                                                       */
  824.   FT_EXPORT( FT_Error )
  825.   FTC_ImageCache_LookupScaler( FTC_ImageCache  cache,
  826.                                FTC_Scaler      scaler,
  827.                                FT_ULong        load_flags,
  828.                                FT_UInt         gindex,
  829.                                FT_Glyph       *aglyph,
  830.                                FTC_Node       *anode );
  833.   /*************************************************************************/
  834.   /*                                                                       */
  835.   /* <Type>                                                                */
  836.   /*    FTC_SBit                                                           */
  837.   /*                                                                       */
  838.   /* <Description>                                                         */
  839.   /*    A handle to a small bitmap descriptor.  See the @FTC_SBitRec       */
  840.   /*    structure for details.                                             */
  841.   /*                                                                       */
  842.   typedef struct FTC_SBitRec_*  FTC_SBit;
  845.   /*************************************************************************/
  846.   /*                                                                       */
  847.   /* <Struct>                                                              */
  848.   /*    FTC_SBitRec                                                        */
  849.   /*                                                                       */
  850.   /* <Description>                                                         */
  851.   /*    A very compact structure used to describe a small glyph bitmap.    */
  852.   /*                                                                       */
  853.   /* <Fields>                                                              */
  854.   /*    width     :: The bitmap width in pixels.                           */
  855.   /*                                                                       */
  856.   /*    height    :: The bitmap height in pixels.                          */
  857.   /*                                                                       */
  858.   /*    left      :: The horizontal distance from the pen position to the  */
  859.   /*                 left bitmap border (a.k.a. `left side bearing', or    */
  860.   /*                 `lsb').                                               */
  861.   /*                                                                       */
  862.   /*    top       :: The vertical distance from the pen position (on the   */
  863.   /*                 baseline) to the upper bitmap border (a.k.a. `top     */
  864.   /*                 side bearing').  The distance is positive for upwards */
  865.   /*                 Y coordinates.                                        */
  866.   /*                                                                       */
  867.   /*    format    :: The format of the glyph bitmap (monochrome or gray).  */
  868.   /*                                                                       */
  869.   /*    max_grays :: Maximum gray level value (in the range 1 to 255).     */
  870.   /*                                                                       */
  871.   /*    pitch     :: The number of bytes per bitmap line.  May be positive */
  872.   /*                 or negative.                                          */
  873.   /*                                                                       */
  874.   /*    xadvance  :: The horizontal advance width in pixels.               */
  875.   /*                                                                       */
  876.   /*    yadvance  :: The vertical advance height in pixels.                */
  877.   /*                                                                       */
  878.   /*    buffer    :: A pointer to the bitmap pixels.                       */
  879.   /*                                                                       */
  880.   typedef struct  FTC_SBitRec_
  881.   {
  882.     FT_Byte   width;
  883.     FT_Byte   height;
  884.     FT_Char   left;
  885.     FT_Char   top;
  887.     FT_Byte   format;
  888.     FT_Byte   max_grays;
  889.     FT_Short  pitch;
  890.     FT_Char   xadvance;
  891.     FT_Char   yadvance;
  893.     FT_Byte*  buffer;
  895.   } FTC_SBitRec;
  898.   /*************************************************************************/
  899.   /*                                                                       */
  900.   /* <Type>                                                                */
  901.   /*    FTC_SBitCache                                                      */
  902.   /*                                                                       */
  903.   /* <Description>                                                         */
  904.   /*    A handle to a small bitmap cache.  These are special cache objects */
  905.   /*    used to store small glyph bitmaps (and anti-aliased pixmaps) in a  */
  906.   /*    much more efficient way than the traditional glyph image cache     */
  907.   /*    implemented by @FTC_ImageCache.                                    */
  908.   /*                                                                       */
  909.   typedef struct FTC_SBitCacheRec_*  FTC_SBitCache;
  912.   /*************************************************************************/
  913.   /*                                                                       */
  914.   /* <Function>                                                            */
  915.   /*    FTC_SBitCache_New                                                  */
  916.   /*                                                                       */
  917.   /* <Description>                                                         */
  918.   /*    Creates a new cache to store small glyph bitmaps.                  */
  919.   /*                                                                       */
  920.   /* <Input>                                                               */
  921.   /*    manager :: A handle to the source cache manager.                   */
  922.   /*                                                                       */
  923.   /* <Output>                                                              */
  924.   /*    acache  :: A handle to the new sbit cache.  NULL in case of error. */
  925.   /*                                                                       */
  926.   /* <Return>                                                              */
  927.   /*    FreeType error code.  0 means success.                             */
  928.   /*                                                                       */
  929.   FT_EXPORT( FT_Error )
  930.   FTC_SBitCache_New( FTC_Manager     manager,
  931.                      FTC_SBitCache  *acache );
  934.   /*************************************************************************/
  935.   /*                                                                       */
  936.   /* <Function>                                                            */
  937.   /*    FTC_SBitCache_Lookup                                               */
  938.   /*                                                                       */
  939.   /* <Description>                                                         */
  940.   /*    Looks up a given small glyph bitmap in a given sbit cache and      */
  941.   /*    `lock' it to prevent its flushing from the cache until needed.     */
  942.   /*                                                                       */
  943.   /* <Input>                                                               */
  944.   /*    cache  :: A handle to the source sbit cache.                       */
  945.   /*                                                                       */
  946.   /*    type   :: A pointer to the glyph image type descriptor.            */
  947.   /*                                                                       */
  948.   /*    gindex :: The glyph index.                                         */
  949.   /*                                                                       */
  950.   /* <Output>                                                              */
  951.   /*    sbit   :: A handle to a small bitmap descriptor.                   */
  952.   /*                                                                       */
  953.   /*    anode  :: Used to return the address of of the corresponding cache */
  954.   /*              node after incrementing its reference count (see note    */
  955.   /*              below).                                                  */
  956.   /*                                                                       */
  957.   /* <Return>                                                              */
  958.   /*    FreeType error code.  0 means success.                             */
  959.   /*                                                                       */
  960.   /* <Note>                                                                */
  961.   /*    The small bitmap descriptor and its bit buffer are owned by the    */
  962.   /*    cache and should never be freed by the application.  They might    */
  963.   /*    as well disappear from memory on the next cache lookup, so don't   */
  964.   /*    treat them as persistent data.                                     */
  965.   /*                                                                       */
  966.   /*    The descriptor's `buffer' field is set to 0 to indicate a missing  */
  967.   /*    glyph bitmap.                                                      */
  968.   /*                                                                       */
  969.   /*    If `anode' is _not_ NULL, it receives the address of the cache     */
  970.   /*    node containing the bitmap, after increasing its reference count.  */
  971.   /*    This ensures that the node (as well as the image) will always be   */
  972.   /*    kept in the cache until you call @FTC_Node_Unref to `release' it.  */
  973.   /*                                                                       */
  974.   /*    If `anode' is NULL, the cache node is left unchanged, which means  */
  975.   /*    that the bitmap could be flushed out of the cache on the next      */
  976.   /*    call to one of the caching sub-system APIs.  Don't assume that it  */
  977.   /*    is persistent!                                                     */
  978.   /*                                                                       */
  979.   FT_EXPORT( FT_Error )
  980.   FTC_SBitCache_Lookup( FTC_SBitCache    cache,
  981.                         FTC_ImageType    type,
  982.                         FT_UInt          gindex,
  983.                         FTC_SBit        *sbit,
  984.                         FTC_Node        *anode );
  987.   /*************************************************************************/
  988.   /*                                                                       */
  989.   /* <Function>                                                            */
  990.   /*    FTC_SBitCache_LookupScaler                                         */
  991.   /*                                                                       */
  992.   /* <Description>                                                         */
  993.   /*    A variant of @FTC_SBitCache_Lookup that uses an @FTC_ScalerRec     */
  994.   /*    to specify the face ID and its size.                               */
  995.   /*                                                                       */
  996.   /* <Input>                                                               */
  997.   /*    cache      :: A handle to the source sbit cache.                   */
  998.   /*                                                                       */
  999.   /*    scaler     :: A pointer to the scaler descriptor.                  */
  1000.   /*                                                                       */
  1001.   /*    load_flags :: The corresponding load flags.                        */
  1002.   /*                                                                       */
  1003.   /*    gindex     :: The glyph index.                                     */
  1004.   /*                                                                       */
  1005.   /* <Output>                                                              */
  1006.   /*    sbit       :: A handle to a small bitmap descriptor.               */
  1007.   /*                                                                       */
  1008.   /*    anode      :: Used to return the address of of the corresponding   */
  1009.   /*                  cache node after incrementing its reference count    */
  1010.   /*                  (see note below).                                    */
  1011.   /*                                                                       */
  1012.   /* <Return>                                                              */
  1013.   /*    FreeType error code.  0 means success.                             */
  1014.   /*                                                                       */
  1015.   /* <Note>                                                                */
  1016.   /*    The small bitmap descriptor and its bit buffer are owned by the    */
  1017.   /*    cache and should never be freed by the application.  They might    */
  1018.   /*    as well disappear from memory on the next cache lookup, so don't   */
  1019.   /*    treat them as persistent data.                                     */
  1020.   /*                                                                       */
  1021.   /*    The descriptor's `buffer' field is set to 0 to indicate a missing  */
  1022.   /*    glyph bitmap.                                                      */
  1023.   /*                                                                       */
  1024.   /*    If `anode' is _not_ NULL, it receives the address of the cache     */
  1025.   /*    node containing the bitmap, after increasing its reference count.  */
  1026.   /*    This ensures that the node (as well as the image) will always be   */
  1027.   /*    kept in the cache until you call @FTC_Node_Unref to `release' it.  */
  1028.   /*                                                                       */
  1029.   /*    If `anode' is NULL, the cache node is left unchanged, which means  */
  1030.   /*    that the bitmap could be flushed out of the cache on the next      */
  1031.   /*    call to one of the caching sub-system APIs.  Don't assume that it  */
  1032.   /*    is persistent!                                                     */
  1033.   /*                                                                       */
  1034.   FT_EXPORT( FT_Error )
  1035.   FTC_SBitCache_LookupScaler( FTC_SBitCache  cache,
  1036.                               FTC_Scaler     scaler,
  1037.                               FT_ULong       load_flags,
  1038.                               FT_UInt        gindex,
  1039.                               FTC_SBit      *sbit,
  1040.                               FTC_Node      *anode );
  1043.  /* */
  1045. #ifdef FT_CONFIG_OPTION_OLD_INTERNALS
  1047.   /*@***********************************************************************/
  1048.   /*                                                                       */
  1049.   /* <Struct>                                                              */
  1050.   /*    FTC_FontRec                                                        */
  1051.   /*                                                                       */
  1052.   /* <Description>                                                         */
  1053.   /*    A simple structure used to describe a given `font' to the cache    */
  1054.   /*    manager.  Note that a `font' is the combination of a given face    */
  1055.   /*    with a given character size.                                       */
  1056.   /*                                                                       */
  1057.   /* <Fields>                                                              */
  1058.   /*    face_id    :: The ID of the face to use.                           */
  1059.   /*                                                                       */
  1060.   /*    pix_width  :: The character width in integer pixels.               */
  1061.   /*                                                                       */
  1062.   /*    pix_height :: The character height in integer pixels.              */
  1063.   /*                                                                       */
  1064.   typedef struct  FTC_FontRec_
  1065.   {
  1066.     FTC_FaceID  face_id;
  1067.     FT_UShort   pix_width;
  1068.     FT_UShort   pix_height;
  1070.   } FTC_FontRec;
  1073.   /* */
  1076. #define FTC_FONT_COMPARE( f1, f2 )                  
  1077.           ( (f1)->face_id    == (f2)->face_id    && 
  1078.             (f1)->pix_width  == (f2)->pix_width  && 
  1079.             (f1)->pix_height == (f2)->pix_height )
  1081. #define FTC_FONT_HASH( f )                              
  1082.           (FT_UInt32)( FTC_FACE_ID_HASH((f)->face_id) ^ 
  1083.                        ((f)->pix_width << 8)          ^ 
  1084.                        ((f)->pix_height)              )
  1086.   typedef FTC_FontRec*  FTC_Font;
  1089.   FT_EXPORT( FT_Error )
  1090.   FTC_Manager_Lookup_Face( FTC_Manager  manager,
  1091.                            FTC_FaceID   face_id,
  1092.                            FT_Face     *aface );
  1094.   FT_EXPORT( FT_Error )
  1095.   FTC_Manager_Lookup_Size( FTC_Manager  manager,
  1096.                            FTC_Font     font,
  1097.                            FT_Face     *aface,
  1098.                            FT_Size     *asize );
  1100. #endif /* FT_CONFIG_OPTION_OLD_INTERNALS */
  1103.  /* */
  1105. FT_END_HEADER
  1107. #endif /* __FTCACHE_H__ */
  1110. /* END */