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 */ 305