Home | History | Annotate | Download | only in cache
      1 /***************************************************************************/
      2 /*                                                                         */
      3 /*  ftcglyph.h                                                             */
      4 /*                                                                         */
      5 /*    FreeType abstract glyph cache (specification).                       */
      6 /*                                                                         */
      7 /*  Copyright 2000-2015 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   /*
     20    *
     21    *  FTC_GCache is an _abstract_ cache object optimized to store glyph
     22    *  data.  It works as follows:
     23    *
     24    *   - It manages FTC_GNode objects. Each one of them can hold one or more
     25    *     glyph `items'.  Item types are not specified in the FTC_GCache but
     26    *     in classes that extend it.
     27    *
     28    *   - Glyph attributes, like face ID, character size, render mode, etc.,
     29    *     can be grouped into abstract `glyph families'.  This avoids storing
     30    *     the attributes within the FTC_GCache, since it is likely that many
     31    *     FTC_GNodes will belong to the same family in typical uses.
     32    *
     33    *   - Each FTC_GNode is thus an FTC_Node with two additional fields:
     34    *
     35    *       * gindex: A glyph index, or the first index in a glyph range.
     36    *       * family: A pointer to a glyph `family'.
     37    *
     38    *   - Family types are not fully specific in the FTC_Family type, but
     39    *     by classes that extend it.
     40    *
     41    *  Note that both FTC_ImageCache and FTC_SBitCache extend FTC_GCache.
     42    *  They share an FTC_Family sub-class called FTC_BasicFamily which is
     43    *  used to store the following data: face ID, pixel/point sizes, load
     44    *  flags.  For more details see the file `src/cache/ftcbasic.c'.
     45    *
     46    *  Client applications can extend FTC_GNode with their own FTC_GNode
     47    *  and FTC_Family sub-classes to implement more complex caches (e.g.,
     48    *  handling automatic synthesis, like obliquing & emboldening, colored
     49    *  glyphs, etc.).
     50    *
     51    *  See also the FTC_ICache & FTC_SCache classes in `ftcimage.h' and
     52    *  `ftcsbits.h', which both extend FTC_GCache with additional
     53    *  optimizations.
     54    *
     55    *  A typical FTC_GCache implementation must provide at least the
     56    *  following:
     57    *
     58    *  - FTC_GNode sub-class, e.g. MyNode, with relevant methods:
     59    *        my_node_new            (must call FTC_GNode_Init)
     60    *        my_node_free           (must call FTC_GNode_Done)
     61    *        my_node_compare        (must call FTC_GNode_Compare)
     62    *        my_node_remove_faceid  (must call ftc_gnode_unselect in case
     63    *                                of match)
     64    *
     65    *  - FTC_Family sub-class, e.g. MyFamily, with relevant methods:
     66    *        my_family_compare
     67    *        my_family_init
     68    *        my_family_reset (optional)
     69    *        my_family_done
     70    *
     71    *  - FTC_GQuery sub-class, e.g. MyQuery, to hold cache-specific query
     72    *    data.
     73    *
     74    *  - Constant structures for a FTC_GNodeClass.
     75    *
     76    *  - MyCacheNew() can be implemented easily as a call to the convenience
     77    *    function FTC_GCache_New.
     78    *
     79    *  - MyCacheLookup with a call to FTC_GCache_Lookup.  This function will
     80    *    automatically:
     81    *
     82    *    - Search for the corresponding family in the cache, or create
     83    *      a new one if necessary.  Put it in FTC_GQUERY(myquery).family
     84    *
     85    *    - Call FTC_Cache_Lookup.
     86    *
     87    *    If it returns NULL, you should create a new node, then call
     88    *    ftc_cache_add as usual.
     89    */
     90 
     91 
     92   /*************************************************************************/
     93   /*                                                                       */
     94   /* Important: The functions defined in this file are only used to        */
     95   /*            implement an abstract glyph cache class.  You need to      */
     96   /*            provide additional logic to implement a complete cache.    */
     97   /*                                                                       */
     98   /*************************************************************************/
     99 
    100 
    101   /*************************************************************************/
    102   /*************************************************************************/
    103   /*************************************************************************/
    104   /*************************************************************************/
    105   /*************************************************************************/
    106   /*********                                                       *********/
    107   /*********             WARNING, THIS IS BETA CODE.               *********/
    108   /*********                                                       *********/
    109   /*************************************************************************/
    110   /*************************************************************************/
    111   /*************************************************************************/
    112   /*************************************************************************/
    113   /*************************************************************************/
    114 
    115 
    116 #ifndef __FTCGLYPH_H__
    117 #define __FTCGLYPH_H__
    118 
    119 
    120 #include <ft2build.h>
    121 #include "ftcmanag.h"
    122 
    123 
    124 FT_BEGIN_HEADER
    125 
    126 
    127  /*
    128   *  We can group glyphs into `families'.  Each family correspond to a
    129   *  given face ID, character size, transform, etc.
    130   *
    131   *  Families are implemented as MRU list nodes.  They are
    132   *  reference-counted.
    133   */
    134 
    135   typedef struct  FTC_FamilyRec_
    136   {
    137     FTC_MruNodeRec    mrunode;
    138     FT_UInt           num_nodes; /* current number of nodes in this family */
    139     FTC_Cache         cache;
    140     FTC_MruListClass  clazz;
    141 
    142   } FTC_FamilyRec, *FTC_Family;
    143 
    144 #define  FTC_FAMILY(x)    ( (FTC_Family)(x) )
    145 #define  FTC_FAMILY_P(x)  ( (FTC_Family*)(x) )
    146 
    147 
    148   typedef struct  FTC_GNodeRec_
    149   {
    150     FTC_NodeRec      node;
    151     FTC_Family       family;
    152     FT_UInt          gindex;
    153 
    154   } FTC_GNodeRec, *FTC_GNode;
    155 
    156 #define FTC_GNODE( x )    ( (FTC_GNode)(x) )
    157 #define FTC_GNODE_P( x )  ( (FTC_GNode*)(x) )
    158 
    159 
    160   typedef struct  FTC_GQueryRec_
    161   {
    162     FT_UInt      gindex;
    163     FTC_Family   family;
    164 
    165   } FTC_GQueryRec, *FTC_GQuery;
    166 
    167 #define FTC_GQUERY( x )  ( (FTC_GQuery)(x) )
    168 
    169 
    170   /*************************************************************************/
    171   /*                                                                       */
    172   /* These functions are exported so that they can be called from          */
    173   /* user-provided cache classes; otherwise, they are really part of the   */
    174   /* cache sub-system internals.                                           */
    175   /*                                                                       */
    176 
    177   /* must be called by derived FTC_Node_InitFunc routines */
    178   FT_LOCAL( void )
    179   FTC_GNode_Init( FTC_GNode   node,
    180                   FT_UInt     gindex,  /* glyph index for node */
    181                   FTC_Family  family );
    182 
    183 #ifdef FTC_INLINE
    184 
    185   /* returns TRUE iff the query's glyph index correspond to the node;  */
    186   /* this assumes that the `family' and `hash' fields of the query are */
    187   /* already correctly set                                             */
    188   FT_LOCAL( FT_Bool )
    189   FTC_GNode_Compare( FTC_GNode   gnode,
    190                      FTC_GQuery  gquery,
    191                      FTC_Cache   cache,
    192                      FT_Bool*    list_changed );
    193 
    194 #endif
    195 
    196   /* call this function to clear a node's family -- this is necessary */
    197   /* to implement the `node_remove_faceid' cache method correctly     */
    198   FT_LOCAL( void )
    199   FTC_GNode_UnselectFamily( FTC_GNode  gnode,
    200                             FTC_Cache  cache );
    201 
    202   /* must be called by derived FTC_Node_DoneFunc routines */
    203   FT_LOCAL( void )
    204   FTC_GNode_Done( FTC_GNode  node,
    205                   FTC_Cache  cache );
    206 
    207 
    208   FT_LOCAL( void )
    209   FTC_Family_Init( FTC_Family  family,
    210                    FTC_Cache   cache );
    211 
    212   typedef struct FTC_GCacheRec_
    213   {
    214     FTC_CacheRec    cache;
    215     FTC_MruListRec  families;
    216 
    217   } FTC_GCacheRec, *FTC_GCache;
    218 
    219 #define FTC_GCACHE( x )  ((FTC_GCache)(x))
    220 
    221 
    222 #if 0
    223   /* can be used as @FTC_Cache_InitFunc */
    224   FT_LOCAL( FT_Error )
    225   FTC_GCache_Init( FTC_GCache  cache );
    226 #endif
    227 
    228 
    229 #if 0
    230   /* can be used as @FTC_Cache_DoneFunc */
    231   FT_LOCAL( void )
    232   FTC_GCache_Done( FTC_GCache  cache );
    233 #endif
    234 
    235 
    236   /* the glyph cache class adds fields for the family implementation */
    237   typedef struct  FTC_GCacheClassRec_
    238   {
    239     FTC_CacheClassRec  clazz;
    240     FTC_MruListClass   family_class;
    241 
    242   } FTC_GCacheClassRec;
    243 
    244   typedef const FTC_GCacheClassRec*   FTC_GCacheClass;
    245 
    246 #define FTC_GCACHE_CLASS( x )  ((FTC_GCacheClass)(x))
    247 
    248 #define FTC_CACHE__GCACHE_CLASS( x ) \
    249           FTC_GCACHE_CLASS( FTC_CACHE(x)->org_class )
    250 #define FTC_CACHE__FAMILY_CLASS( x ) \
    251           ( (FTC_MruListClass)FTC_CACHE__GCACHE_CLASS( x )->family_class )
    252 
    253 
    254   /* convenience function; use it instead of FTC_Manager_Register_Cache */
    255   FT_LOCAL( FT_Error )
    256   FTC_GCache_New( FTC_Manager       manager,
    257                   FTC_GCacheClass   clazz,
    258                   FTC_GCache       *acache );
    259 
    260 #ifndef FTC_INLINE
    261   FT_LOCAL( FT_Error )
    262   FTC_GCache_Lookup( FTC_GCache   cache,
    263                      FT_Offset    hash,
    264                      FT_UInt      gindex,
    265                      FTC_GQuery   query,
    266                      FTC_Node    *anode );
    267 #endif
    268 
    269 
    270   /* */
    271 
    272 
    273 #define FTC_FAMILY_FREE( family, cache )                      \
    274           FTC_MruList_Remove( &FTC_GCACHE((cache))->families, \
    275                               (FTC_MruNode)(family) )
    276 
    277 
    278 #ifdef FTC_INLINE
    279 
    280 #define FTC_GCACHE_LOOKUP_CMP( cache, famcmp, nodecmp, hash,                \
    281                                gindex, query, node, error )                 \
    282   FT_BEGIN_STMNT                                                            \
    283     FTC_GCache               _gcache   = FTC_GCACHE( cache );               \
    284     FTC_GQuery               _gquery   = (FTC_GQuery)( query );             \
    285     FTC_MruNode_CompareFunc  _fcompare = (FTC_MruNode_CompareFunc)(famcmp); \
    286     FTC_MruNode              _mrunode;                                      \
    287                                                                             \
    288                                                                             \
    289     _gquery->gindex = (gindex);                                             \
    290                                                                             \
    291     FTC_MRULIST_LOOKUP_CMP( &_gcache->families, _gquery, _fcompare,         \
    292                             _mrunode, error );                              \
    293     _gquery->family = FTC_FAMILY( _mrunode );                               \
    294     if ( !error )                                                           \
    295     {                                                                       \
    296       FTC_Family  _gqfamily = _gquery->family;                              \
    297                                                                             \
    298                                                                             \
    299       _gqfamily->num_nodes++;                                               \
    300                                                                             \
    301       FTC_CACHE_LOOKUP_CMP( cache, nodecmp, hash, query, node, error );     \
    302                                                                             \
    303       if ( --_gqfamily->num_nodes == 0 )                                    \
    304         FTC_FAMILY_FREE( _gqfamily, _gcache );                              \
    305     }                                                                       \
    306   FT_END_STMNT
    307   /* */
    308 
    309 #else /* !FTC_INLINE */
    310 
    311 #define FTC_GCACHE_LOOKUP_CMP( cache, famcmp, nodecmp, hash,          \
    312                                gindex, query, node, error )           \
    313    FT_BEGIN_STMNT                                                     \
    314                                                                       \
    315      error = FTC_GCache_Lookup( FTC_GCACHE( cache ), hash, gindex,    \
    316                                 FTC_GQUERY( query ), &node );         \
    317                                                                       \
    318    FT_END_STMNT
    319 
    320 #endif /* !FTC_INLINE */
    321 
    322 
    323 FT_END_HEADER
    324 
    325 
    326 #endif /* __FTCGLYPH_H__ */
    327 
    328 
    329 /* END */
    330