src/cache/ftcmanag.h

   1 /****************************************************************************
   2  *
   3  * ftcmanag.h
   4  *
   5  *   FreeType Cache Manager (specification).
   6  *
   7  * Copyright (C) 2000-2023 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 <freetype/ftcache.h>
  67 #include "ftcmru.h"
  68 #include "ftccache.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   typedef struct  FTC_ManagerRec_
  91   {
  92     FT_Library          library;
  93     FT_Memory           memory;
  94
  95     FTC_Node            nodes_list;
  96     FT_Offset           max_weight;
  97     FT_Offset           cur_weight;
  98     FT_UInt             num_nodes;
  99
 100     FTC_Cache           caches[FTC_MAX_CACHES];
 101     FT_UInt             num_caches;
 102
 103     FTC_MruListRec      faces;
 104     FTC_MruListRec      sizes;
 105
 106     FT_Pointer          request_data;
 107     FTC_Face_Requester  request_face;
 108
 109   } FTC_ManagerRec;
 110
 111
 112   /**************************************************************************
 113    *
 114    * @Function:
 115    *   FTC_Manager_Compress
 116    *
 117    * @Description:
 118    *   This function is used to check the state of the cache manager if
 119    *   its `num_bytes' field is greater than its `max_bytes' field.  It
 120    *   will flush as many old cache nodes as possible (ignoring cache
 121    *   nodes with a non-zero reference count).
 122    *
 123    * @InOut:
 124    *   manager ::
 125    *     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 */