lib/freetype/include/freetype/cache/ftccache.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  ftccache.h                                                             */
   4 /*                                                                         */
   5 /*    FreeType internal cache interface (specification).                   */
   6 /*                                                                         */
   7 /*  Copyright 2000-2001, 2002 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 __FTCCACHE_H__
  20 #define __FTCCACHE_H__
  21
  22
  23 /* define to allow cache lookup inlining */
  24 #define  FTC_CACHE_USE_INLINE
  25
  26
  27 FT_BEGIN_HEADER
  28
  29   /* handle to cache object */
  30   typedef struct FTC_CacheRec_*  FTC_Cache;
  31
  32   /* handle to cache class */
  33   typedef const struct FTC_Cache_ClassRec_*  FTC_Cache_Class;
  34
  35   /* handle to cache node family */
  36   typedef struct FTC_FamilyRec_*  FTC_Family;
  37
  38   /* handle to cache root query */
  39   typedef struct FTC_QueryRec_*  FTC_Query;
  40
  41
  42   /*************************************************************************/
  43   /*************************************************************************/
  44   /*****                                                               *****/
  45   /*****                   CACHE NODE DEFINITIONS                      *****/
  46   /*****                                                               *****/
  47   /*************************************************************************/
  48   /*************************************************************************/
  49
  50   /*************************************************************************/
  51   /*                                                                       */
  52   /* Each cache controls one or more cache nodes.  Each node is part of    */
  53   /* the global_lru list of the manager.  Its `data' field however is used */
  54   /* as a reference count for now.                                         */
  55   /*                                                                       */
  56   /* A node can be anything, depending on the type of information held by  */
  57   /* the cache.  It can be an individual glyph image, a set of bitmaps     */
  58   /* glyphs for a given size, some metrics, etc.                           */
  59   /*                                                                       */
  60   /*************************************************************************/
  61
  62   /* structure size should be 20 bytes on 32-bits machines */
  63   typedef struct  FTC_NodeRec_
  64   {
  65     FTC_Node   mru_next;     /* circular mru list pointer           */
  66     FTC_Node   mru_prev;     /* circular mru list pointer           */
  67     FTC_Node   link;         /* used for hashing                    */
  68     FT_UInt32  hash;         /* used for hashing too                */
  69     FT_UShort  fam_index;    /* index of family the node belongs to */
  70     FT_Short   ref_count;    /* reference count for this node       */
  71
  72   } FTC_NodeRec;
  73
  74
  75 #define FTC_NODE( x )    ( (FTC_Node)(x) )
  76 #define FTC_NODE_P( x )  ( (FTC_Node*)(x) )
  77
  78
  79   /*************************************************************************/
  80   /*                                                                       */
  81   /* These functions are exported so that they can be called from          */
  82   /* user-provided cache classes; otherwise, they are really part of the   */
  83   /* cache sub-system internals.                                           */
  84   /*                                                                       */
  85
  86   /* can be used as a FTC_Node_DoneFunc */
  87   FT_EXPORT( void )
  88   ftc_node_done( FTC_Node   node,
  89                  FTC_Cache  cache );
  90
  91   /* reserved for manager's use */
  92   FT_EXPORT( void )
  93   ftc_node_destroy( FTC_Node     node,
  94                     FTC_Manager  manager );
  95
  96
  97   /*************************************************************************/
  98   /*************************************************************************/
  99   /*****                                                               *****/
 100   /*****                   CACHE QUERY DEFINITIONS                     *****/
 101   /*****                                                               *****/
 102   /*************************************************************************/
 103   /*************************************************************************/
 104
 105   /* A structure modelling a cache node query.  The following fields must  */
 106   /* all be set by the @FTC_Family_CompareFunc method of a cache's family  */
 107   /* list.                                                                 */
 108   /*                                                                       */
 109   typedef struct  FTC_QueryRec_
 110   {
 111     FTC_Family  family;
 112     FT_UFast    hash;
 113
 114   } FTC_QueryRec;
 115
 116
 117 #define FTC_QUERY( x )    ( (FTC_Query)(x) )
 118 #define FTC_QUERY_P( x )  ( (FTC_Query*)(x) )
 119
 120
 121   /*************************************************************************/
 122   /*************************************************************************/
 123   /*****                                                               *****/
 124   /*****                   CACHE FAMILY DEFINITIONS                    *****/
 125   /*****                                                               *****/
 126   /*************************************************************************/
 127   /*************************************************************************/
 128
 129   typedef struct  FTC_FamilyRec_
 130   {
 131     FT_LruNodeRec  lru;
 132     FTC_Cache      cache;
 133     FT_UInt        num_nodes;
 134     FT_UInt        fam_index;
 135
 136   } FTC_FamilyRec;
 137
 138
 139 #define FTC_FAMILY( x )    ( (FTC_Family)(x) )
 140 #define FTC_FAMILY_P( x )  ( (FTC_Family*)(x) )
 141
 142
 143   /*************************************************************************/
 144   /*                                                                       */
 145   /* These functions are exported so that they can be called from          */
 146   /* user-provided cache classes; otherwise, they are really part of the   */
 147   /* cache sub-system internals.                                           */
 148   /*                                                                       */
 149
 150   /* must be called by any FTC_Node_InitFunc routine */
 151   FT_EXPORT( FT_Error )
 152   ftc_family_init( FTC_Family  family,
 153                    FTC_Query   query,
 154                    FTC_Cache   cache );
 155
 156
 157   /* can be used as a FTC_Family_DoneFunc; otherwise, must be called */
 158   /* by any family finalizer function                                */
 159   FT_EXPORT( void )
 160   ftc_family_done( FTC_Family  family );
 161
 162
 163   /*************************************************************************/
 164   /*************************************************************************/
 165   /*****                                                               *****/
 166   /*****                       CACHE DEFINITIONS                       *****/
 167   /*****                                                               *****/
 168   /*************************************************************************/
 169   /*************************************************************************/
 170
 171   /* each cache really implements a dynamic hash table to manage its nodes */
 172   typedef struct  FTC_CacheRec_
 173   {
 174     FTC_Manager          manager;
 175     FT_Memory            memory;
 176     FTC_Cache_Class      clazz;
 177
 178     FT_UInt              cache_index;  /* in manager's table         */
 179     FT_Pointer           cache_data;   /* used by cache node methods */
 180
 181     FT_UFast             p;
 182     FT_UFast             mask;
 183     FT_Long              slack;
 184     FTC_Node*            buckets;
 185
 186     FT_LruList_ClassRec  family_class;
 187     FT_LruList           families;
 188
 189   } FTC_CacheRec;
 190
 191
 192 #define FTC_CACHE( x )    ( (FTC_Cache)(x) )
 193 #define FTC_CACHE_P( x )  ( (FTC_Cache*)(x) )
 194
 195
 196   /* initialize a given cache */
 197   typedef FT_Error
 198   (*FTC_Cache_InitFunc)( FTC_Cache  cache );
 199
 200   /* clear a cache */
 201   typedef void
 202   (*FTC_Cache_ClearFunc)( FTC_Cache  cache );
 203
 204   /* finalize a given cache */
 205   typedef void
 206   (*FTC_Cache_DoneFunc)( FTC_Cache  cache );
 207
 208
 209   typedef FT_Error
 210   (*FTC_Family_InitFunc)( FTC_Family  family,
 211                           FTC_Query   query,
 212                           FTC_Cache   cache );
 213
 214   typedef FT_Int
 215   (*FTC_Family_CompareFunc)( FTC_Family  family,
 216                              FTC_Query   query );
 217
 218   typedef void
 219   (*FTC_Family_DoneFunc)( FTC_Family  family,
 220                           FTC_Cache   cache );
 221
 222   /* initialize a new cache node */
 223   typedef FT_Error
 224   (*FTC_Node_InitFunc)( FTC_Node    node,
 225                         FT_Pointer  type,
 226                         FTC_Cache   cache );
 227
 228   /* compute the weight of a given cache node */
 229   typedef FT_ULong
 230   (*FTC_Node_WeightFunc)( FTC_Node   node,
 231                           FTC_Cache  cache );
 232
 233   /* compare a node to a given key pair */
 234   typedef FT_Bool
 235   (*FTC_Node_CompareFunc)( FTC_Node    node,
 236                            FT_Pointer  key,
 237                            FTC_Cache   cache );
 238
 239   /* finalize a given cache node */
 240   typedef void
 241   (*FTC_Node_DoneFunc)( FTC_Node   node,
 242                         FTC_Cache  cache );
 243
 244
 245   typedef struct  FTC_Cache_ClassRec_
 246   {
 247     FT_UInt                 cache_size;
 248     FTC_Cache_InitFunc      cache_init;
 249     FTC_Cache_ClearFunc     cache_clear;
 250     FTC_Cache_DoneFunc      cache_done;
 251
 252     FT_UInt                 family_size;
 253     FTC_Family_InitFunc     family_init;
 254     FTC_Family_CompareFunc  family_compare;
 255     FTC_Family_DoneFunc     family_done;
 256
 257     FT_UInt                 node_size;
 258     FTC_Node_InitFunc       node_init;
 259     FTC_Node_WeightFunc     node_weight;
 260     FTC_Node_CompareFunc    node_compare;
 261     FTC_Node_DoneFunc       node_done;
 262
 263   } FTC_Cache_ClassRec;
 264
 265
 266   /* */
 267
 268
 269   /*************************************************************************/
 270   /*                                                                       */
 271   /* These functions are exported so that they can be called from          */
 272   /* user-provided cache classes; otherwise, they are really part of the   */
 273   /* cache sub-system internals.                                           */
 274   /*                                                                       */
 275
 276   /* can be used directly as FTC_Cache_DoneFunc(), or called by custom */
 277   /* cache finalizers                                                  */
 278   FT_EXPORT( void )
 279   ftc_cache_done( FTC_Cache  cache );
 280
 281   /* can be used directly as FTC_Cache_ClearFunc(), or called by custom */
 282   /* cache clear routines                                               */
 283   FT_EXPORT( void )
 284   ftc_cache_clear( FTC_Cache  cache );
 285
 286   /* initalize the hash table within the cache */
 287   FT_EXPORT( FT_Error )
 288   ftc_cache_init( FTC_Cache  cache );
 289
 290   /* can be called when the key's hash value has been computed */
 291   FT_EXPORT( FT_Error )
 292   ftc_cache_lookup( FTC_Cache  cache,
 293                     FTC_Query  query,
 294                     FTC_Node  *anode );
 295
 296  /* */
 297
 298 FT_END_HEADER
 299
 300
 301 #endif /* __FTCCACHE_H__ */
 302
 303
 304 /* END */