src/cache/ftcmanag.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  ftcmanag.h                                                             */
   4 /*                                                                         */
   5 /*    FreeType Cache Manager (specification).                              */
   6 /*                                                                         */
   7 /*  Copyright 2000-2001, 2003, 2004, 2006, 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   /*************************************************************************/
  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   /*    and 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 "ftcmru.h"
  69 #include "ftccache.h"
  70
  71
  72 FT_BEGIN_HEADER
  73
  74
  75   /*************************************************************************/
  76   /*                                                                       */
  77   /* <Section>                                                             */
  78   /*    cache_subsystem                                                    */
  79   /*                                                                       */
  80   /*************************************************************************/
  81
  82
  83 #define FTC_MAX_FACES_DEFAULT  2
  84 #define FTC_MAX_SIZES_DEFAULT  4
  85 #define FTC_MAX_BYTES_DEFAULT  200000L  /* ~200kByte by default */
  86
  87   /* maximum number of caches registered in a single manager */
  88 #define FTC_MAX_CACHES         16
  89
  90
  91   typedef struct  FTC_ManagerRec_
  92   {
  93     FT_Library          library;
  94     FT_Memory           memory;
  95
  96     FTC_Node            nodes_list;
  97     FT_Offset           max_weight;
  98     FT_Offset           cur_weight;
  99     FT_UInt             num_nodes;
 100
 101     FTC_Cache           caches[FTC_MAX_CACHES];
 102     FT_UInt             num_caches;
 103
 104     FTC_MruListRec      faces;
 105     FTC_MruListRec      sizes;
 106
 107     FT_Pointer          request_data;
 108     FTC_Face_Requester  request_face;
 109
 110   } FTC_ManagerRec;
 111
 112
 113   /*************************************************************************/
 114   /*                                                                       */
 115   /* <Function>                                                            */
 116   /*    FTC_Manager_Compress                                               */
 117   /*                                                                       */
 118   /* <Description>                                                         */
 119   /*    This function is used to check the state of the cache manager if   */
 120   /*    its `num_bytes' field is greater than its `max_bytes' field.  It   */
 121   /*    will flush as many old cache nodes as possible (ignoring cache     */
 122   /*    nodes with a non-zero reference count).                            */
 123   /*                                                                       */
 124   /* <InOut>                                                               */
 125   /*    manager :: A handle to the cache manager.                          */
 126   /*                                                                       */
 127   /* <Note>                                                                */
 128   /*    Client applications should not call this function directly.  It is */
 129   /*    normally invoked by specific cache implementations.                */
 130   /*                                                                       */
 131   /*    The reason this function is exported is to allow client-specific   */
 132   /*    cache classes.                                                     */
 133   /*                                                                       */
 134   FT_LOCAL( void )
 135   FTC_Manager_Compress( FTC_Manager  manager );
 136
 137
 138   /* try to flush `count' old nodes from the cache; return the number
 139    * of really flushed nodes
 140    */
 141   FT_LOCAL( FT_UInt )
 142   FTC_Manager_FlushN( FTC_Manager  manager,
 143                       FT_UInt      count );
 144
 145
 146   /* this must be used internally for the moment */
 147   FT_LOCAL( FT_Error )
 148   FTC_Manager_RegisterCache( FTC_Manager      manager,
 149                              FTC_CacheClass   clazz,
 150                              FTC_Cache       *acache );
 151
 152  /* */
 153
 154 #define FTC_SCALER_COMPARE( a, b )                \
 155     ( (a)->face_id      == (b)->face_id      &&   \
 156       (a)->width        == (b)->width        &&   \
 157       (a)->height       == (b)->height       &&   \
 158       ((a)->pixel != 0) == ((b)->pixel != 0) &&   \
 159       ( (a)->pixel ||                             \
 160         ( (a)->x_res == (b)->x_res &&             \
 161           (a)->y_res == (b)->y_res ) ) )
 162
 163 #define FTC_SCALER_HASH( q )                                 \
 164     ( _FTC_FACE_ID_HASH( (q)->face_id ) +                     \
 165       (q)->width + (q)->height*7 +                           \
 166       ( (q)->pixel ? 0 : ( (q)->x_res*33 ^ (q)->y_res*61 ) ) )
 167
 168  /* */
 169
 170 FT_END_HEADER
 171
 172 #endif /* __FTCMANAG_H__ */
 173
 174
 175 /* END */