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