1 /***************************************************************************/ 2 /* */ 3 /* ftincrem.h */ 4 /* */ 5 /* FreeType incremental loading (specification). */ 6 /* */ 7 /* Copyright 2002, 2003, 2006, 2007, 2008 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 __FTINCREM_H__ 20 #define __FTINCREM_H__ 21 22 #include <ft2build.h> 23 #include FT_FREETYPE_H 24 25 #ifdef FREETYPE_H 26 #error "freetype.h of FreeType 1 has been loaded!" 27 #error "Please fix the directory search order for header files" 28 #error "so that freetype.h of FreeType 2 is found first." 29 #endif 30 31 32 FT_BEGIN_HEADER 33 34 /*************************************************************************** 35 * 36 * @section: 37 * incremental 38 * 39 * @title: 40 * Incremental Loading 41 * 42 * @abstract: 43 * Custom Glyph Loading. 44 * 45 * @description: 46 * This section contains various functions used to perform so-called 47 * `incremental' glyph loading. This is a mode where all glyphs loaded 48 * from a given @FT_Face are provided by the client application, 49 * 50 * Apart from that, all other tables are loaded normally from the font 51 * file. This mode is useful when FreeType is used within another 52 * engine, e.g., a PostScript Imaging Processor. 53 * 54 * To enable this mode, you must use @FT_Open_Face, passing an 55 * @FT_Parameter with the @FT_PARAM_TAG_INCREMENTAL tag and an 56 * @FT_Incremental_Interface value. See the comments for 57 * @FT_Incremental_InterfaceRec for an example. 58 * 59 */ 60 61 62 /*************************************************************************** 63 * 64 * @type: 65 * FT_Incremental 66 * 67 * @description: 68 * An opaque type describing a user-provided object used to implement 69 * `incremental' glyph loading within FreeType. This is used to support 70 * embedded fonts in certain environments (e.g., PostScript interpreters), 71 * where the glyph data isn't in the font file, or must be overridden by 72 * different values. 73 * 74 * @note: 75 * It is up to client applications to create and implement @FT_Incremental 76 * objects, as long as they provide implementations for the methods 77 * @FT_Incremental_GetGlyphDataFunc, @FT_Incremental_FreeGlyphDataFunc 78 * and @FT_Incremental_GetGlyphMetricsFunc. 79 * 80 * See the description of @FT_Incremental_InterfaceRec to understand how 81 * to use incremental objects with FreeType. 82 * 83 */ 84 typedef struct FT_IncrementalRec_* FT_Incremental; 85 86 87 /*************************************************************************** 88 * 89 * @struct: 90 * FT_Incremental_MetricsRec 91 * 92 * @description: 93 * A small structure used to contain the basic glyph metrics returned 94 * by the @FT_Incremental_GetGlyphMetricsFunc method. 95 * 96 * @fields: 97 * bearing_x :: 98 * Left bearing, in font units. 99 * 100 * bearing_y :: 101 * Top bearing, in font units. 102 * 103 * advance :: 104 * Glyph advance, in font units. 105 * 106 * @note: 107 * These correspond to horizontal or vertical metrics depending on the 108 * value of the `vertical' argument to the function 109 * @FT_Incremental_GetGlyphMetricsFunc. 110 * 111 */ 112 typedef struct FT_Incremental_MetricsRec_ 113 { 114 FT_Long bearing_x; 115 FT_Long bearing_y; 116 FT_Long advance; 117 118 } FT_Incremental_MetricsRec; 119 120 121 /*************************************************************************** 122 * 123 * @struct: 124 * FT_Incremental_Metrics 125 * 126 * @description: 127 * A handle to an @FT_Incremental_MetricsRec structure. 128 * 129 */ 130 typedef struct FT_Incremental_MetricsRec_* FT_Incremental_Metrics; 131 132 133 /*************************************************************************** 134 * 135 * @type: 136 * FT_Incremental_GetGlyphDataFunc 137 * 138 * @description: 139 * A function called by FreeType to access a given glyph's data bytes 140 * during @FT_Load_Glyph or @FT_Load_Char if incremental loading is 141 * enabled. 142 * 143 * Note that the format of the glyph's data bytes depends on the font 144 * file format. For TrueType, it must correspond to the raw bytes within 145 * the `glyf' table. For PostScript formats, it must correspond to the 146 * *unencrypted* charstring bytes, without any `lenIV' header. It is 147 * undefined for any other format. 148 * 149 * @input: 150 * incremental :: 151 * Handle to an opaque @FT_Incremental handle provided by the client 152 * application. 153 * 154 * glyph_index :: 155 * Index of relevant glyph. 156 * 157 * @output: 158 * adata :: 159 * A structure describing the returned glyph data bytes (which will be 160 * accessed as a read-only byte block). 161 * 162 * @return: 163 * FreeType error code. 0~means success. 164 * 165 * @note: 166 * If this function returns successfully the method 167 * @FT_Incremental_FreeGlyphDataFunc will be called later to release 168 * the data bytes. 169 * 170 * Nested calls to @FT_Incremental_GetGlyphDataFunc can happen for 171 * compound glyphs. 172 * 173 */ 174 typedef FT_Error 175 (*FT_Incremental_GetGlyphDataFunc)( FT_Incremental incremental, 176 FT_UInt glyph_index, 177 FT_Data* adata ); 178 179 180 /*************************************************************************** 181 * 182 * @type: 183 * FT_Incremental_FreeGlyphDataFunc 184 * 185 * @description: 186 * A function used to release the glyph data bytes returned by a 187 * successful call to @FT_Incremental_GetGlyphDataFunc. 188 * 189 * @input: 190 * incremental :: 191 * A handle to an opaque @FT_Incremental handle provided by the client 192 * application. 193 * 194 * data :: 195 * A structure describing the glyph data bytes (which will be accessed 196 * as a read-only byte block). 197 * 198 */ 199 typedef void 200 (*FT_Incremental_FreeGlyphDataFunc)( FT_Incremental incremental, 201 FT_Data* data ); 202 203 204 /*************************************************************************** 205 * 206 * @type: 207 * FT_Incremental_GetGlyphMetricsFunc 208 * 209 * @description: 210 * A function used to retrieve the basic metrics of a given glyph index 211 * before accessing its data. This is necessary because, in certain 212 * formats like TrueType, the metrics are stored in a different place from 213 * the glyph images proper. 214 * 215 * @input: 216 * incremental :: 217 * A handle to an opaque @FT_Incremental handle provided by the client 218 * application. 219 * 220 * glyph_index :: 221 * Index of relevant glyph. 222 * 223 * vertical :: 224 * If true, return vertical metrics. 225 * 226 * ametrics :: 227 * This parameter is used for both input and output. 228 * The original glyph metrics, if any, in font units. If metrics are 229 * not available all the values must be set to zero. 230 * 231 * @output: 232 * ametrics :: 233 * The replacement glyph metrics in font units. 234 * 235 */ 236 typedef FT_Error 237 (*FT_Incremental_GetGlyphMetricsFunc) 238 ( FT_Incremental incremental, 239 FT_UInt glyph_index, 240 FT_Bool vertical, 241 FT_Incremental_MetricsRec *ametrics ); 242 243 244 /************************************************************************** 245 * 246 * @struct: 247 * FT_Incremental_FuncsRec 248 * 249 * @description: 250 * A table of functions for accessing fonts that load data 251 * incrementally. Used in @FT_Incremental_InterfaceRec. 252 * 253 * @fields: 254 * get_glyph_data :: 255 * The function to get glyph data. Must not be null. 256 * 257 * free_glyph_data :: 258 * The function to release glyph data. Must not be null. 259 * 260 * get_glyph_metrics :: 261 * The function to get glyph metrics. May be null if the font does 262 * not provide overriding glyph metrics. 263 * 264 */ 265 typedef struct FT_Incremental_FuncsRec_ 266 { 267 FT_Incremental_GetGlyphDataFunc get_glyph_data; 268 FT_Incremental_FreeGlyphDataFunc free_glyph_data; 269 FT_Incremental_GetGlyphMetricsFunc get_glyph_metrics; 270 271 } FT_Incremental_FuncsRec; 272 273 274 /*************************************************************************** 275 * 276 * @struct: 277 * FT_Incremental_InterfaceRec 278 * 279 * @description: 280 * A structure to be used with @FT_Open_Face to indicate that the user 281 * wants to support incremental glyph loading. You should use it with 282 * @FT_PARAM_TAG_INCREMENTAL as in the following example: 283 * 284 * { 285 * FT_Incremental_InterfaceRec inc_int; 286 * FT_Parameter parameter; 287 * FT_Open_Args open_args; 288 * 289 * 290 * // set up incremental descriptor 291 * inc_int.funcs = my_funcs; 292 * inc_int.object = my_object; 293 * 294 * // set up optional parameter 295 * parameter.tag = FT_PARAM_TAG_INCREMENTAL; 296 * parameter.data = &inc_int; 297 * 298 * // set up FT_Open_Args structure 299 * open_args.flags = FT_OPEN_PATHNAME | FT_OPEN_PARAMS; 300 * open_args.pathname = my_font_pathname; 301 * open_args.num_params = 1; 302 * open_args.params = ¶meter; // we use one optional argument 303 * 304 * // open the font 305 * error = FT_Open_Face( library, &open_args, index, &face ); 306 * ... 307 * } 308 * 309 */ 310 typedef struct FT_Incremental_InterfaceRec_ 311 { 312 const FT_Incremental_FuncsRec* funcs; 313 FT_Incremental object; 314 315 } FT_Incremental_InterfaceRec; 316 317 318 /*************************************************************************** 319 * 320 * @type: 321 * FT_Incremental_Interface 322 * 323 * @description: 324 * A pointer to an @FT_Incremental_InterfaceRec structure. 325 * 326 */ 327 typedef FT_Incremental_InterfaceRec* FT_Incremental_Interface; 328 329 330 /*************************************************************************** 331 * 332 * @constant: 333 * FT_PARAM_TAG_INCREMENTAL 334 * 335 * @description: 336 * A constant used as the tag of @FT_Parameter structures to indicate 337 * an incremental loading object to be used by FreeType. 338 * 339 */ 340 #define FT_PARAM_TAG_INCREMENTAL FT_MAKE_TAG( 'i', 'n', 'c', 'r' ) 341 342 /* */ 343 344 FT_END_HEADER 345 346 #endif /* __FTINCREM_H__ */ 347 348 349 /* END */ 350