QRScanner/mobile/jni/thirdparty/freetype/src/cache/ftcglyph.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  ftcglyph.h                                                             */
   4 /*                                                                         */
   5 /*    FreeType abstract glyph cache (specification).                       */
   6 /*                                                                         */
   7 /*  Copyright 2000-2001, 2003, 2004, 2006, 2007, 2011 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_PtrDist   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 */