1 /***************************************************************************/ 2 /* */ 3 /* ftcimage.h */ 4 /* */ 5 /* FreeType Image cache (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 /*************************************************************************/ 20 /* */ 21 /* Each image cache really manages FT_Glyph objects. */ 22 /* */ 23 /*************************************************************************/ 24 25 26 #ifndef __FTCIMAGE_H__ 27 #define __FTCIMAGE_H__ 28 29 30 #include <ft2build.h> 31 #include FT_CACHE_H 32 33 34 FT_BEGIN_HEADER 35 36 37 /*************************************************************************/ 38 /* */ 39 /* <Section> */ 40 /* cache_subsystem */ 41 /* */ 42 /*************************************************************************/ 43 44 45 /*************************************************************************/ 46 /*************************************************************************/ 47 /*************************************************************************/ 48 /***** *****/ 49 /***** IMAGE CACHE OBJECT *****/ 50 /***** *****/ 51 /*************************************************************************/ 52 /*************************************************************************/ 53 /*************************************************************************/ 54 55 56 /************************************************************************** 57 * 58 * @struct: 59 * FTC_ImageTypeRec 60 * 61 * @description: 62 * A simple structure used to describe the type of glyph image to be 63 * loaded into the cache. 64 * 65 * @fields: 66 * font :: An @FTC_FontRec used to describe the glyph's face and size. 67 * 68 * flags :: The load flags to be applied when loading the glyph; see 69 * the @FT_LOAD_XXX constants for details. 70 * 71 * @note: 72 * This type completely replaces the @FTC_Image_Desc structure which is 73 * now obsolete. 74 */ 75 typedef struct FTC_ImageTypeRec_ 76 { 77 FTC_FontRec font; 78 FT_Int32 flags; 79 80 } FTC_ImageTypeRec; 81 82 typedef struct FTC_ImageTypeRec_* FTC_ImageType; 83 84 /* */ 85 86 #define FTC_IMAGE_TYPE_COMPARE( d1, d2 ) \ 87 ( FTC_FONT_COMPARE( &(d1)->font, &(d2)->font ) && \ 88 (d1)->flags == (d2)->flags ) 89 90 #define FTC_IMAGE_TYPE_HASH( d ) \ 91 (FT_UFast)( FTC_FONT_HASH( &(d)->font ) ^ \ 92 ( (d)->flags << 4 ) ) 93 94 95 /*************************************************************************/ 96 /* */ 97 /* <Type> */ 98 /* FTC_ImageCache */ 99 /* */ 100 /* <Description> */ 101 /* A handle to an glyph image cache object. They are designed to */ 102 /* hold many distinct glyph images while not exceeding a certain */ 103 /* memory threshold. */ 104 /* */ 105 typedef struct FTC_ImageCacheRec_* FTC_ImageCache; 106 107 108 /*************************************************************************/ 109 /* */ 110 /* <Function> */ 111 /* FTC_ImageCache_New */ 112 /* */ 113 /* <Description> */ 114 /* Creates a new glyph image cache. */ 115 /* */ 116 /* <Input> */ 117 /* manager :: The parent manager for the image cache. */ 118 /* */ 119 /* <Output> */ 120 /* acache :: A handle to the new glyph image cache object. */ 121 /* */ 122 /* <Return> */ 123 /* FreeType error code. 0 means success. */ 124 /* */ 125 FT_EXPORT( FT_Error ) 126 FTC_ImageCache_New( FTC_Manager manager, 127 FTC_ImageCache *acache ); 128 129 130 /*************************************************************************/ 131 /* */ 132 /* <Function> */ 133 /* FTC_ImageCache_Lookup */ 134 /* */ 135 /* <Description> */ 136 /* Retrieves a given glyph image from a glyph image cache. */ 137 /* */ 138 /* <Input> */ 139 /* cache :: A handle to the source glyph image cache. */ 140 /* */ 141 /* type :: A pointer to a glyph image type descriptor. */ 142 /* */ 143 /* gindex :: The glyph index to retrieve. */ 144 /* */ 145 /* <Output> */ 146 /* aglyph :: The corresponding @FT_Glyph object. 0 in case of */ 147 /* failure. */ 148 /* */ 149 /* anode :: Used to return the address of of the corresponding cache */ 150 /* node after incrementing its reference count (see note */ 151 /* below). */ 152 /* */ 153 /* <Return> */ 154 /* FreeType error code. 0 means success. */ 155 /* */ 156 /* <Note> */ 157 /* The returned glyph is owned and managed by the glyph image cache. */ 158 /* Never try to transform or discard it manually! You can however */ 159 /* create a copy with @FT_Glyph_Copy and modify the new one. */ 160 /* */ 161 /* If "anode" is _not_ NULL, it receives the address of the cache */ 162 /* node containing the glyph image, after increasing its reference */ 163 /* count. This ensures that the node (as well as the FT_Glyph) will */ 164 /* always be kept in the cache until you call @FTC_Node_Unref to */ 165 /* "release" it. */ 166 /* */ 167 /* If "anode" is NULL, the cache node is left unchanged, which means */ 168 /* that the FT_Glyph could be flushed out of the cache on the next */ 169 /* call to one of the caching sub-system APIs. Don't assume that it */ 170 /* is persistent! */ 171 /* */ 172 FT_EXPORT( FT_Error ) 173 FTC_ImageCache_Lookup( FTC_ImageCache cache, 174 FTC_ImageType type, 175 FT_UInt gindex, 176 FT_Glyph *aglyph, 177 FTC_Node *anode ); 178 179 /* */ 180 181 #define ftc_image_format( x ) ( (x) & 7 ) 182 183 184 #define ftc_image_format_bitmap 0x0000 185 #define ftc_image_format_outline 0x0001 186 187 #define ftc_image_format_mask 0x000F 188 189 #define ftc_image_flag_monochrome 0x0010 190 #define ftc_image_flag_unhinted 0x0020 191 #define ftc_image_flag_autohinted 0x0040 192 #define ftc_image_flag_unscaled 0x0080 193 #define ftc_image_flag_no_sbits 0x0100 194 195 /* monochrome bitmap */ 196 #define ftc_image_mono ftc_image_format_bitmap | \ 197 ftc_image_flag_monochrome 198 199 /* anti-aliased bitmap */ 200 #define ftc_image_grays ftc_image_format_bitmap 201 202 /* scaled outline */ 203 #define ftc_image_outline ftc_image_format_outline 204 205 /*************************************************************************/ 206 /* */ 207 /* <Struct> */ 208 /* FTC_Image_Desc */ 209 /* */ 210 /* <Description> */ 211 /* THIS TYPE IS DEPRECATED. Use @FTC_ImageDesc instead. */ 212 /* */ 213 /* A simple structure used to describe a given glyph image category. */ 214 /* */ 215 /* <Fields> */ 216 /* size :: An @FTC_SizeRec used to describe the glyph's face */ 217 /* and size. */ 218 /* */ 219 /* image_type :: The glyph image's type. */ 220 /* */ 221 typedef struct FTC_Image_Desc_ 222 { 223 FTC_FontRec font; 224 FT_UInt image_type; 225 226 } FTC_Image_Desc; 227 228 229 /*************************************************************************/ 230 /* */ 231 /* <Type> */ 232 /* FTC_Image_Cache */ 233 /* */ 234 /* <Description> */ 235 /* THIS TYPE IS DEPRECATED. Use @FTC_ImageCache instead. */ 236 /* */ 237 typedef FTC_ImageCache FTC_Image_Cache; 238 239 240 /*************************************************************************/ 241 /* */ 242 /* <Function> */ 243 /* FTC_Image_Cache_New */ 244 /* */ 245 /* <Description> */ 246 /* THIS FUNCTION IS DEPRECATED. Use @FTC_ImageCache_New instead. */ 247 /* */ 248 /* Creates a new glyph image cache. */ 249 /* */ 250 /* <Input> */ 251 /* manager :: The parent manager for the image cache. */ 252 /* */ 253 /* <Output> */ 254 /* acache :: A handle to the new glyph image cache object. */ 255 /* */ 256 /* <Return> */ 257 /* FreeType error code. 0 means success. */ 258 /* */ 259 FT_EXPORT( FT_Error ) 260 FTC_Image_Cache_New( FTC_Manager manager, 261 FTC_Image_Cache *acache ); 262 263 264 /*************************************************************************/ 265 /* */ 266 /* <Function> */ 267 /* FTC_Image_Cache_Lookup */ 268 /* */ 269 /* <Description> */ 270 /* THIS FUNCTION IS DEPRECATED. Use @FTC_ImageCache_Lookup instead. */ 271 /* */ 272 /* <Input> */ 273 /* cache :: A handle to the source glyph image cache. */ 274 /* */ 275 /* desc :: A pointer to a glyph image descriptor. */ 276 /* */ 277 /* gindex :: The glyph index to retrieve. */ 278 /* */ 279 /* <Output> */ 280 /* aglyph :: The corresponding @FT_Glyph object. 0 in case of */ 281 /* failure. */ 282 /* */ 283 /* <Return> */ 284 /* FreeType error code. 0 means success. */ 285 /* */ 286 /* <Note> */ 287 /* The returned glyph is owned and managed by the glyph image cache. */ 288 /* Never try to transform or discard it manually! You can however */ 289 /* create a copy with @FT_Glyph_Copy and modify the new one. */ 290 /* */ 291 /* Because the glyph image cache limits the total amount of memory */ 292 /* taken by the glyphs it holds, the returned glyph might disappear */ 293 /* on a later invocation of this function! It is a cache after */ 294 /* all... */ 295 /* */ 296 /* Use this function to "lock" the glyph as long as it is needed. */ 297 /* */ 298 FT_EXPORT( FT_Error ) 299 FTC_Image_Cache_Lookup( FTC_Image_Cache cache, 300 FTC_Image_Desc* desc, 301 FT_UInt gindex, 302 FT_Glyph *aglyph ); 303 304 /* */ 305 306 FT_END_HEADER 307 308 309 #endif /* __FTCIMAGE_H__ */ 310 311 312 /* END */ 313