1 /***************************************************************************/ 2 /* */ 3 /* ftcache.h */ 4 /* */ 5 /* FreeType Cache subsystem (specification). */ 6 /* */ 7 /* Copyright 1996-2001, 2002, 2003 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 /*************************************************************************/ 22 /*************************************************************************/ 23 /*************************************************************************/ 24 /********* *********/ 25 /********* WARNING, THIS IS BETA CODE. *********/ 26 /********* *********/ 27 /*************************************************************************/ 28 /*************************************************************************/ 29 /*************************************************************************/ 30 /*************************************************************************/ 31 /*************************************************************************/ 32 33 34 #ifndef __FTCACHE_H__ 35 #define __FTCACHE_H__ 36 37 38 #include <ft2build.h> 39 #include FT_GLYPH_H 40 41 42 FT_BEGIN_HEADER 43 44 45 /*************************************************************************/ 46 /* */ 47 /* <Section> */ 48 /* cache_subsystem */ 49 /* */ 50 /* <Title> */ 51 /* Cache Sub-System */ 52 /* */ 53 /* <Abstract> */ 54 /* How to cache face, size, and glyph data with FreeType 2. */ 55 /* */ 56 /* <Description> */ 57 /* This section describes the FreeType 2 cache sub-system which is */ 58 /* stile in beta. */ 59 /* */ 60 /* <Order> */ 61 /* FTC_Manager */ 62 /* FTC_FaceID */ 63 /* FTC_Face_Requester */ 64 /* */ 65 /* FTC_Manager_New */ 66 /* FTC_Manager_Lookup_Face */ 67 /* FTC_Manager_Lookup_Size */ 68 /* */ 69 /* FTC_Node */ 70 /* FTC_Node_Ref */ 71 /* FTC_Node_Unref */ 72 /* */ 73 /* FTC_Font */ 74 /* FTC_ImageCache */ 75 /* FTC_ImageCache_New */ 76 /* FTC_ImageCache_Lookup */ 77 /* */ 78 /* FTC_SBit */ 79 /* FTC_SBitCache */ 80 /* FTC_SBitCache_New */ 81 /* FTC_SBitCache_Lookup */ 82 /* */ 83 /* */ 84 /* FTC_Image_Desc */ 85 /* FTC_Image_Cache */ 86 /* FTC_Image_Cache_Lookup */ 87 /* */ 88 /* FTC_SBit_Cache */ 89 /* FTC_SBit_Cache_Lookup */ 90 /* */ 91 /*************************************************************************/ 92 93 94 /*************************************************************************/ 95 /*************************************************************************/ 96 /*************************************************************************/ 97 /***** *****/ 98 /***** BASIC TYPE DEFINITIONS *****/ 99 /***** *****/ 100 /*************************************************************************/ 101 /*************************************************************************/ 102 /*************************************************************************/ 103 104 105 /*************************************************************************/ 106 /* */ 107 /* <Type> */ 108 /* FTC_FaceID */ 109 /* */ 110 /* <Description> */ 111 /* A generic pointer type that is used to identity face objects. The */ 112 /* contents of such objects is application-dependent. */ 113 /* */ 114 typedef FT_Pointer FTC_FaceID; 115 116 117 /*************************************************************************/ 118 /* */ 119 /* <FuncType> */ 120 /* FTC_Face_Requester */ 121 /* */ 122 /* <Description> */ 123 /* A callback function provided by client applications. It is used */ 124 /* to translate a given @FTC_FaceID into a new valid @FT_Face object. */ 125 /* */ 126 /* <Input> */ 127 /* face_id :: The face ID to resolve. */ 128 /* */ 129 /* library :: A handle to a FreeType library object. */ 130 /* */ 131 /* data :: Application-provided request data. */ 132 /* */ 133 /* <Output> */ 134 /* aface :: A new @FT_Face handle. */ 135 /* */ 136 /* <Return> */ 137 /* FreeType error code. 0 means success. */ 138 /* */ 139 /* <Note> */ 140 /* The face requester should not perform funny things on the returned */ 141 /* face object, like creating a new @FT_Size for it, or setting a */ 142 /* transformation through @FT_Set_Transform! */ 143 /* */ 144 typedef FT_Error 145 (*FTC_Face_Requester)( FTC_FaceID face_id, 146 FT_Library library, 147 FT_Pointer request_data, 148 FT_Face* aface ); 149 150 151 /*************************************************************************/ 152 /* */ 153 /* <Struct> */ 154 /* FTC_FontRec */ 155 /* */ 156 /* <Description> */ 157 /* A simple structure used to describe a given `font' to the cache */ 158 /* manager. Note that a `font' is the combination of a given face */ 159 /* with a given character size. */ 160 /* */ 161 /* <Fields> */ 162 /* face_id :: The ID of the face to use. */ 163 /* */ 164 /* pix_width :: The character width in integer pixels. */ 165 /* */ 166 /* pix_height :: The character height in integer pixels. */ 167 /* */ 168 typedef struct FTC_FontRec_ 169 { 170 FTC_FaceID face_id; 171 FT_UShort pix_width; 172 FT_UShort pix_height; 173 174 } FTC_FontRec; 175 176 177 /* */ 178 179 180 #define FTC_FONT_COMPARE( f1, f2 ) \ 181 ( (f1)->face_id == (f2)->face_id && \ 182 (f1)->pix_width == (f2)->pix_width && \ 183 (f1)->pix_height == (f2)->pix_height ) 184 185 #define FT_POINTER_TO_ULONG( p ) ((FT_ULong)(FT_Pointer)(p)) 186 187 #define FTC_FACE_ID_HASH( i ) \ 188 ((FT_UInt32)(( FT_POINTER_TO_ULONG( i ) >> 3 ) ^ \ 189 ( FT_POINTER_TO_ULONG( i ) << 7 ) ) ) 190 191 #define FTC_FONT_HASH( f ) \ 192 (FT_UInt32)( FTC_FACE_ID_HASH((f)->face_id) ^ \ 193 ((f)->pix_width << 8) ^ \ 194 ((f)->pix_height) ) 195 196 197 /*************************************************************************/ 198 /* */ 199 /* <Type> */ 200 /* FTC_Font */ 201 /* */ 202 /* <Description> */ 203 /* A simple handle to an @FTC_FontRec structure. */ 204 /* */ 205 typedef FTC_FontRec* FTC_Font; 206 207 208 /*************************************************************************/ 209 /*************************************************************************/ 210 /*************************************************************************/ 211 /***** *****/ 212 /***** CACHE MANAGER OBJECT *****/ 213 /***** *****/ 214 /*************************************************************************/ 215 /*************************************************************************/ 216 /*************************************************************************/ 217 218 219 /*************************************************************************/ 220 /* */ 221 /* <Type> */ 222 /* FTC_Manager */ 223 /* */ 224 /* <Description> */ 225 /* This object is used to cache one or more @FT_Face objects, along */ 226 /* with corresponding @FT_Size objects. */ 227 /* */ 228 typedef struct FTC_ManagerRec_* FTC_Manager; 229 230 231 /*************************************************************************/ 232 /* */ 233 /* <Type> */ 234 /* FTC_Node */ 235 /* */ 236 /* <Description> */ 237 /* An opaque handle to a cache node object. Each cache node is */ 238 /* reference-counted. A node with a count of 0 might be flushed */ 239 /* out of a full cache whenever a lookup request is performed. */ 240 /* */ 241 /* If you lookup nodes, you have the ability to "acquire" them, i.e., */ 242 /* to increment their reference count. This will prevent the node */ 243 /* from being flushed out of the cache until you explicitly "release" */ 244 /* it (see @FTC_Node_Unref). */ 245 /* */ 246 /* See also @FTC_SBitCache_Lookup and @FTC_ImageCache_Lookup. */ 247 /* */ 248 typedef struct FTC_NodeRec_* FTC_Node; 249 250 251 /*************************************************************************/ 252 /* */ 253 /* <Function> */ 254 /* FTC_Manager_New */ 255 /* */ 256 /* <Description> */ 257 /* Creates a new cache manager. */ 258 /* */ 259 /* <Input> */ 260 /* library :: The parent FreeType library handle to use. */ 261 /* */ 262 /* max_faces :: Maximum number of faces to keep alive in manager. */ 263 /* Use 0 for defaults. */ 264 /* */ 265 /* max_sizes :: Maximum number of sizes to keep alive in manager. */ 266 /* Use 0 for defaults. */ 267 /* */ 268 /* max_bytes :: Maximum number of bytes to use for cached data. */ 269 /* Use 0 for defaults. */ 270 /* */ 271 /* requester :: An application-provided callback used to translate */ 272 /* face IDs into real @FT_Face objects. */ 273 /* */ 274 /* req_data :: A generic pointer that is passed to the requester */ 275 /* each time it is called (see @FTC_Face_Requester). */ 276 /* */ 277 /* <Output> */ 278 /* amanager :: A handle to a new manager object. 0 in case of */ 279 /* failure. */ 280 /* */ 281 /* <Return> */ 282 /* FreeType error code. 0 means success. */ 283 /* */ 284 FT_EXPORT( FT_Error ) 285 FTC_Manager_New( FT_Library library, 286 FT_UInt max_faces, 287 FT_UInt max_sizes, 288 FT_ULong max_bytes, 289 FTC_Face_Requester requester, 290 FT_Pointer req_data, 291 FTC_Manager *amanager ); 292 293 294 /*************************************************************************/ 295 /* */ 296 /* <Function> */ 297 /* FTC_Manager_Reset */ 298 /* */ 299 /* <Description> */ 300 /* Empties a given cache manager. This simply gets rid of all the */ 301 /* currently cached @FT_Face and @FT_Size objects within the manager. */ 302 /* */ 303 /* <InOut> */ 304 /* manager :: A handle to the manager. */ 305 /* */ 306 FT_EXPORT( void ) 307 FTC_Manager_Reset( FTC_Manager manager ); 308 309 310 /*************************************************************************/ 311 /* */ 312 /* <Function> */ 313 /* FTC_Manager_Done */ 314 /* */ 315 /* <Description> */ 316 /* Destroys a given manager after emptying it. */ 317 /* */ 318 /* <Input> */ 319 /* manager :: A handle to the target cache manager object. */ 320 /* */ 321 FT_EXPORT( void ) 322 FTC_Manager_Done( FTC_Manager manager ); 323 324 325 /*************************************************************************/ 326 /* */ 327 /* <Function> */ 328 /* FTC_Manager_Lookup_Face */ 329 /* */ 330 /* <Description> */ 331 /* Retrieves the @FT_Face object that corresponds to a given face ID */ 332 /* through a cache manager. */ 333 /* */ 334 /* <Input> */ 335 /* manager :: A handle to the cache manager. */ 336 /* */ 337 /* face_id :: The ID of the face object. */ 338 /* */ 339 /* <Output> */ 340 /* aface :: A handle to the face object. */ 341 /* */ 342 /* <Return> */ 343 /* FreeType error code. 0 means success. */ 344 /* */ 345 /* <Note> */ 346 /* The returned @FT_Face object is always owned by the manager. You */ 347 /* should never try to discard it yourself. */ 348 /* */ 349 /* The @FT_Face object doesn't necessarily have a current size object */ 350 /* (i.e., face->size can be 0). If you need a specific `font size', */ 351 /* use @FTC_Manager_Lookup_Size instead. */ 352 /* */ 353 /* Never change the face's transformation matrix (i.e., never call */ 354 /* the @FT_Set_Transform function) on a returned face! If you need */ 355 /* to transform glyphs, do it yourself after glyph loading. */ 356 /* */ 357 FT_EXPORT( FT_Error ) 358 FTC_Manager_Lookup_Face( FTC_Manager manager, 359 FTC_FaceID face_id, 360 FT_Face *aface ); 361 362 363 /*************************************************************************/ 364 /* */ 365 /* <Function> */ 366 /* FTC_Manager_Lookup_Size */ 367 /* */ 368 /* <Description> */ 369 /* Retrieves the @FT_Face and @FT_Size objects that correspond to a */ 370 /* given font. */ 371 /* */ 372 /* <Input> */ 373 /* manager :: A handle to the cache manager. */ 374 /* */ 375 /* font :: The font to use. */ 376 /* */ 377 /* <Output> */ 378 /* aface :: A pointer to the handle of the face object. Set it to */ 379 /* zero if you don't need it. */ 380 /* */ 381 /* asize :: A pointer to the handle of the size object. Set it to */ 382 /* zero if you don't need it. */ 383 /* */ 384 /* <Return> */ 385 /* FreeType error code. 0 means success. */ 386 /* */ 387 /* <Note> */ 388 /* The returned @FT_Face object is always owned by the manager. You */ 389 /* should never try to discard it yourself. */ 390 /* */ 391 /* Never change the face's transformation matrix (i.e., never call */ 392 /* the @FT_Set_Transform function) on a returned face! If you need */ 393 /* to transform glyphs, do it yourself after glyph loading. */ 394 /* */ 395 /* Similarly, the returned @FT_Size object is always owned by the */ 396 /* manager. You should never try to discard it, and never change its */ 397 /* settings with @FT_Set_Pixel_Sizes or @FT_Set_Char_Size! */ 398 /* */ 399 /* The returned size object is the face's current size, which means */ 400 /* that you can call @FT_Load_Glyph with the face if you need to. */ 401 /* */ 402 FT_EXPORT( FT_Error ) 403 FTC_Manager_Lookup_Size( FTC_Manager manager, 404 FTC_Font font, 405 FT_Face *aface, 406 FT_Size *asize ); 407 408 409 FT_END_HEADER 410 411 #endif /* __FTCACHE_H__ */ 412 413 414 /* END */ 415