libraries/freetype-2.0.5/include/freetype/cache/ftcmanag.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  ftcmanag.h                                                             */
   4 /*                                                                         */
   5 /*    FreeType Cache Manager (specification).                              */
   6 /*                                                                         */
   7 /*  Copyright 2000-2001 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   /* A cache manager is in charge of the following:                        */
  22   /*                                                                       */
  23   /*  - Maintain a mapping between generic FTC_FaceIDs and live FT_Face    */
  24   /*    objects.  The mapping itself is performed through a user-provided  */
  25   /*    callback.  However, the manager maintains a small cache of FT_Face */
  26   /*    & FT_Size objects in order to speed up things considerably.        */
  27   /*                                                                       */
  28   /*  - Manage one or more cache objects.  Each cache is in charge of      */
  29   /*    holding a varying number of `cache nodes'.  Each cache node        */
  30   /*    represents a minimal amount of individually accessible cached      */
  31   /*    data.  For example, a cache node can be an FT_Glyph image          */
  32   /*    containing a vector outline, or some glyph metrics, or anything    */
  33   /*    else.                                                              */
  34   /*                                                                       */
  35   /*    Each cache node has a certain size in bytes that is added to the   */
  36   /*    total amount of `cache memory' within the manager.                 */
  37   /*                                                                       */
  38   /*    All cache nodes are located in a global LRU list, where the oldest */
  39   /*    node is at the tail of the list.                                   */
  40   /*                                                                       */
  41   /*    Each node belongs to a single cache, and includes a reference      */
  42   /*    count to avoid destroying it (due to caching).                     */
  43   /*                                                                       */
  44   /*************************************************************************/
  45
  46
  47   /*************************************************************************/
  48   /*************************************************************************/
  49   /*************************************************************************/
  50   /*************************************************************************/
  51   /*************************************************************************/
  52   /*********                                                       *********/
  53   /*********             WARNING, THIS IS BETA CODE.               *********/
  54   /*********                                                       *********/
  55   /*************************************************************************/
  56   /*************************************************************************/
  57   /*************************************************************************/
  58   /*************************************************************************/
  59   /*************************************************************************/
  60
  61
  62 #ifndef __FTCMANAG_H__
  63 #define __FTCMANAG_H__
  64
  65
  66 #include <ft2build.h>
  67 #include FT_CACHE_H
  68 #include FT_CACHE_INTERNAL_LRU_H
  69
  70
  71 FT_BEGIN_HEADER
  72
  73
  74   /*************************************************************************/
  75   /*                                                                       */
  76   /* <Section>                                                             */
  77   /*    cache_subsystem                                                    */
  78   /*                                                                       */
  79   /*************************************************************************/
  80
  81
  82 #define FTC_MAX_FACES_DEFAULT  2
  83 #define FTC_MAX_SIZES_DEFAULT  4
  84 #define FTC_MAX_BYTES_DEFAULT  200000L  /* 200kByte by default! */
  85
  86   /* maximum number of caches registered in a single manager */
  87 #define FTC_MAX_CACHES         16
  88
  89
  90   /*************************************************************************/
  91   /*                                                                       */
  92   /* <Struct>                                                              */
  93   /*    FTC_ManagerRec                                                     */
  94   /*                                                                       */
  95   /* <Description>                                                         */
  96   /*    The cache manager structure.                                       */
  97   /*                                                                       */
  98   /* <Fields>                                                              */
  99   /*    library      :: A handle to a FreeType library instance.           */
 100   /*                                                                       */
 101   /*    faces_lru    :: The lru list of FT_Face objects in the cache.      */
 102   /*                                                                       */
 103   /*    sizes_lru    :: The lru list of FT_Size objects in the cache.      */
 104   /*                                                                       */
 105   /*    max_bytes    :: The maximum number of bytes to be allocated in the */
 106   /*                    cache.  This is only related to the byte size of   */
 107   /*                    the nodes cached by the manager.                   */
 108   /*                                                                       */
 109   /*    num_bytes    :: The current number of bytes allocated in the       */
 110   /*                    cache.  Only related to the byte size of cached    */
 111   /*                    nodes.                                             */
 112   /*                                                                       */
 113   /*    num_nodes    :: The current number of nodes in the manager.        */
 114   /*                                                                       */
 115   /*    global_lru   :: The global lru list of all cache nodes.            */
 116   /*                                                                       */
 117   /*    caches       :: A table of installed/registered cache objects.     */
 118   /*                                                                       */
 119   /*    request_data :: User-provided data passed to the requester.        */
 120   /*                                                                       */
 121   /*    request_face :: User-provided function used to implement a mapping */
 122   /*                    between abstract FTC_FaceIDs and real FT_Face      */
 123   /*                    objects.                                           */
 124   /*                                                                       */
 125   typedef struct  FTC_ManagerRec_
 126   {
 127     FT_Library          library;
 128     FT_Lru              faces_lru;
 129     FT_Lru              sizes_lru;
 130
 131     FT_ULong            max_bytes;
 132     FT_ULong            num_bytes;
 133     FT_UInt             num_nodes;
 134     FT_ListRec          global_lru;
 135     FTC_Cache           caches[FTC_MAX_CACHES];
 136
 137     FT_Pointer          request_data;
 138     FTC_Face_Requester  request_face;
 139
 140   } FTC_ManagerRec;
 141
 142
 143   /*************************************************************************/
 144   /*                                                                       */
 145   /* <Function>                                                            */
 146   /*    FTC_Manager_Compress                                               */
 147   /*                                                                       */
 148   /* <Description>                                                         */
 149   /*    This function is used to check the state of the cache manager if   */
 150   /*    its `num_bytes' field is greater than its `max_bytes' field.  It   */
 151   /*    will flush as many old cache nodes as possible (ignoring cache     */
 152   /*    nodes with a non-zero reference count).                            */
 153   /*                                                                       */
 154   /* <InOut>                                                               */
 155   /*    manager :: A handle to the cache manager.                          */
 156   /*                                                                       */
 157   /* <Note>                                                                */
 158   /*    Client applications should not call this function directly.  It is */
 159   /*    normally invoked by specific cache implementations.                */
 160   /*                                                                       */
 161   /*    The reason this function is exported is to allow client-specific   */
 162   /*    cache classes.                                                     */
 163   /*                                                                       */
 164   FT_EXPORT( void )
 165   FTC_Manager_Compress( FTC_Manager  manager );
 166
 167
 168   /*************************************************************************/
 169   /*************************************************************************/
 170   /*****                                                               *****/
 171   /*****                   CACHE NODE DEFINITIONS                      *****/
 172   /*****                                                               *****/
 173   /*************************************************************************/
 174   /*************************************************************************/
 175
 176
 177   /*************************************************************************/
 178   /*                                                                       */
 179   /* Each cache controls one or more cache nodes.  Each node is part of    */
 180   /* the global_lru list of the manager.  Its `data' field however is used */
 181   /* as a reference count for now.                                         */
 182   /*                                                                       */
 183   /* A node can be anything, depending on the type of information held by  */
 184   /* the cache.  It can be an individual glyph image, a set of bitmaps     */
 185   /* glyphs for a given size, some metrics, etc.                           */
 186   /*                                                                       */
 187
 188   typedef FT_ListNodeRec     FTC_CacheNodeRec;
 189   typedef FTC_CacheNodeRec*  FTC_CacheNode;
 190
 191
 192   /* the field `cachenode.data' is typecast to this type */
 193   typedef struct  FTC_CacheNode_Data_
 194   {
 195     FT_UShort  cache_index;
 196     FT_Short   ref_count;
 197
 198   } FTC_CacheNode_Data;
 199
 200
 201   /* return a pointer to FTC_CacheNode_Data contained in a */
 202   /* CacheNode's `data' field                              */
 203 #define FTC_CACHENODE_TO_DATA_P( n ) \
 204           ( (FTC_CacheNode_Data*)&(n)->data )
 205
 206 #define FTC_LIST_TO_CACHENODE( n )  ( (FTC_CacheNode)(n) )
 207
 208
 209   /*************************************************************************/
 210   /*                                                                       */
 211   /* <FuncType>                                                            */
 212   /*    FTC_CacheNode_SizeFunc                                             */
 213   /*                                                                       */
 214   /* <Description>                                                         */
 215   /*    A function used to compute the total size in bytes of a given      */
 216   /*    cache node.  It is used by the cache manager to compute the number */
 217   /*    of old nodes to flush when the cache is full.                      */
 218   /*                                                                       */
 219   /* <Input>                                                               */
 220   /*    node       :: A handle to the target cache node.                   */
 221   /*                                                                       */
 222   /*    cache_data :: A generic pointer passed to the destructor.          */
 223   /*                                                                       */
 224   /* <Return>                                                              */
 225   /*    The size of a given cache node in bytes.                           */
 226   /*                                                                       */
 227   typedef FT_ULong
 228   (*FTC_CacheNode_SizeFunc)( FTC_CacheNode  node,
 229                              FT_Pointer     cache_data );
 230
 231
 232   /*************************************************************************/
 233   /*                                                                       */
 234   /* <FuncType>                                                            */
 235   /*    FTC_CacheNode_DestroyFunc                                          */
 236   /*                                                                       */
 237   /* <Description>                                                         */
 238   /*    A function used to destroy a given cache node.  It is called by    */
 239   /*    the manager when the cache is full and old nodes need to be        */
 240   /*    flushed out.                                                       */
 241   /*                                                                       */
 242   /* <Input>                                                               */
 243   /*    node       :: A handle to the target cache node.                   */
 244   /*                                                                       */
 245   /*    cache_data :: A generic pointer passed to the destructor.          */
 246   /*                                                                       */
 247   typedef void
 248   (*FTC_CacheNode_DestroyFunc)( FTC_CacheNode  node,
 249                                 FT_Pointer     cache_data );
 250
 251
 252   /*************************************************************************/
 253   /*                                                                       */
 254   /* <Struct>                                                              */
 255   /*    FTC_CacheNode_Class                                                */
 256   /*                                                                       */
 257   /* <Description>                                                         */
 258   /*    A very simple structure used to describe a cache node's class to   */
 259   /*    the cache manager.                                                 */
 260   /*                                                                       */
 261   /* <Fields>                                                              */
 262   /*    size_node    :: A function used to size the node.                  */
 263   /*                                                                       */
 264   /*    destroy_node :: A function used to destroy the node.               */
 265   /*                                                                       */
 266   /* <Note>                                                                */
 267   /*    The cache node class doesn't include a `new_node' function because */
 268   /*    the cache manager never allocates cache node directly; it          */
 269   /*    delegates this task to its cache objects.                          */
 270   /*                                                                       */
 271   typedef struct  FTC_CacheNode_Class_
 272   {
 273     FTC_CacheNode_SizeFunc     size_node;
 274     FTC_CacheNode_DestroyFunc  destroy_node;
 275
 276   } FTC_CacheNode_Class;
 277
 278
 279   /*************************************************************************/
 280   /*************************************************************************/
 281   /*****                                                               *****/
 282   /*****                       CACHE DEFINITIONS                       *****/
 283   /*****                                                               *****/
 284   /*************************************************************************/
 285   /*************************************************************************/
 286
 287
 288   /*************************************************************************/
 289   /*                                                                       */
 290   /* <FuncType>                                                            */
 291   /*    FTC_Cache_InitFunc                                                 */
 292   /*                                                                       */
 293   /* <Description>                                                         */
 294   /*    A function used to initialize a given cache object.                */
 295   /*                                                                       */
 296   /* <Input>                                                               */
 297   /*    cache :: A handle to the new cache.                                */
 298   /*                                                                       */
 299   typedef FT_Error
 300   (*FTC_Cache_InitFunc)( FTC_Cache  cache );
 301
 302
 303   /*************************************************************************/
 304   /*                                                                       */
 305   /* <FuncType>                                                            */
 306   /*    FTC_Cache_DoneFunc                                                 */
 307   /*                                                                       */
 308   /* <Description>                                                         */
 309   /*    A function to finalize a given cache object.                       */
 310   /*                                                                       */
 311   /* <Input>                                                               */
 312   /*    cache :: A handle to the target cache.                             */
 313   /*                                                                       */
 314   typedef void
 315   (*FTC_Cache_DoneFunc)( FTC_Cache  cache );
 316
 317
 318   /*************************************************************************/
 319   /*                                                                       */
 320   /* <Struct>                                                              */
 321   /*    FTC_Cache_Class                                                    */
 322   /*                                                                       */
 323   /* <Description>                                                         */
 324   /*    A structure used to describe a given cache object class to the     */
 325   /*    cache manager.                                                     */
 326   /*                                                                       */
 327   /* <Fields>                                                              */
 328   /*    cache_byte_size :: The size of the cache object in bytes.          */
 329   /*                                                                       */
 330   /*    init_cache      :: The cache object initializer.                   */
 331   /*                                                                       */
 332   /*    done_cache      :: The cache object finalizer.                     */
 333   /*                                                                       */
 334   struct  FTC_Cache_Class_
 335   {
 336     FT_UInt             cache_byte_size;
 337     FTC_Cache_InitFunc  init_cache;
 338     FTC_Cache_DoneFunc  done_cache;
 339   };
 340
 341
 342   /*************************************************************************/
 343   /*                                                                       */
 344   /* <Struct>                                                              */
 345   /*    FTC_CacheRec                                                       */
 346   /*                                                                       */
 347   /* <Description>                                                         */
 348   /*    A structure used to describe an abstract cache object.             */
 349   /*                                                                       */
 350   /* <Fields>                                                              */
 351   /*    manager     :: A handle to the parent cache manager.               */
 352   /*                                                                       */
 353   /*    memory      :: A handle to the memory manager.                     */
 354   /*                                                                       */
 355   /*    clazz       :: A pointer to the cache class.                       */
 356   /*                                                                       */
 357   /*    node_clazz  :: A pointer to the cache's node class.                */
 358   /*                                                                       */
 359   /*    cache_index :: An index of the cache in the manager's table.       */
 360   /*                                                                       */
 361   /*    cache_data  :: Data passed to the cache node                       */
 362   /*                   constructor/finalizer.                              */
 363   /*                                                                       */
 364   typedef struct  FTC_CacheRec_
 365   {
 366     FTC_Manager           manager;
 367     FT_Memory             memory;
 368     FTC_Cache_Class*      clazz;
 369     FTC_CacheNode_Class*  node_clazz;
 370
 371     FT_UInt               cache_index;  /* in manager's table           */
 372     FT_Pointer            cache_data;   /* passed to cache node methods */
 373
 374   } FTC_CacheRec;
 375
 376
 377   /* */
 378
 379
 380 FT_END_HEADER
 381
 382 #endif /* __FTCMANAG_H__ */
 383
 384
 385 /* END */