• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /****************************************************************************
2  *
3  * ftcmanag.h
4  *
5  *   FreeType Cache Manager (specification).
6  *
7  * Copyright 2000-2018 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 ::
126    *     A handle to the cache manager.
127    *
128    * @Note:
129    *   Client applications should not call this function directly.  It is
130    *   normally invoked by specific cache implementations.
131    *
132    *   The reason this function is exported is to allow client-specific
133    *   cache classes.
134    */
135   FT_LOCAL( void )
136   FTC_Manager_Compress( FTC_Manager  manager );
137 
138 
139   /* try to flush `count' old nodes from the cache; return the number
140    * of really flushed nodes
141    */
142   FT_LOCAL( FT_UInt )
143   FTC_Manager_FlushN( FTC_Manager  manager,
144                       FT_UInt      count );
145 
146 
147   /* this must be used internally for the moment */
148   FT_LOCAL( FT_Error )
149   FTC_Manager_RegisterCache( FTC_Manager      manager,
150                              FTC_CacheClass   clazz,
151                              FTC_Cache       *acache );
152 
153  /* */
154 
155 #define FTC_SCALER_COMPARE( a, b )                \
156     ( (a)->face_id      == (b)->face_id      &&   \
157       (a)->width        == (b)->width        &&   \
158       (a)->height       == (b)->height       &&   \
159       ((a)->pixel != 0) == ((b)->pixel != 0) &&   \
160       ( (a)->pixel ||                             \
161         ( (a)->x_res == (b)->x_res &&             \
162           (a)->y_res == (b)->y_res ) ) )
163 
164 #define FTC_SCALER_HASH( q )                                 \
165     ( FTC_FACE_ID_HASH( (q)->face_id ) +                     \
166       (q)->width + (q)->height*7 +                           \
167       ( (q)->pixel ? 0 : ( (q)->x_res*33 ^ (q)->y_res*61 ) ) )
168 
169  /* */
170 
171 FT_END_HEADER
172 
173 #endif /* FTCMANAG_H_ */
174 
175 
176 /* END */
177