1 /***************************************************************************/ 2 /* */ 3 /* ftincrem.h */ 4 /* */ 5 /* FreeType incremental loading (specification). */ 6 /* */ 7 /* Copyright 2002, 2003, 2006, 2007, 2008, 2010 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 * Horizontal component of glyph advance, in font units. 105 * 106 * advance_v :: 107 * Vertical component of glyph advance, in font units. 108 * 109 * @note: 110 * These correspond to horizontal or vertical metrics depending on the 111 * value of the `vertical' argument to the function 112 * @FT_Incremental_GetGlyphMetricsFunc. 113 * 114 */ 115 typedef struct FT_Incremental_MetricsRec_ 116 { 117 FT_Long bearing_x; 118 FT_Long bearing_y; 119 FT_Long advance; 120 FT_Long advance_v; /* since 2.3.12 */ 121 122 } FT_Incremental_MetricsRec; 123 124 125 /*************************************************************************** 126 * 127 * @struct: 128 * FT_Incremental_Metrics 129 * 130 * @description: 131 * A handle to an @FT_Incremental_MetricsRec structure. 132 * 133 */ 134 typedef struct FT_Incremental_MetricsRec_* FT_Incremental_Metrics; 135 136 137 /*************************************************************************** 138 * 139 * @type: 140 * FT_Incremental_GetGlyphDataFunc 141 * 142 * @description: 143 * A function called by FreeType to access a given glyph's data bytes 144 * during @FT_Load_Glyph or @FT_Load_Char if incremental loading is 145 * enabled. 146 * 147 * Note that the format of the glyph's data bytes depends on the font 148 * file format. For TrueType, it must correspond to the raw bytes within 149 * the `glyf' table. For PostScript formats, it must correspond to the 150 * *unencrypted* charstring bytes, without any `lenIV' header. It is 151 * undefined for any other format. 152 * 153 * @input: 154 * incremental :: 155 * Handle to an opaque @FT_Incremental handle provided by the client 156 * application. 157 * 158 * glyph_index :: 159 * Index of relevant glyph. 160 * 161 * @output: 162 * adata :: 163 * A structure describing the returned glyph data bytes (which will be 164 * accessed as a read-only byte block). 165 * 166 * @return: 167 * FreeType error code. 0~means success. 168 * 169 * @note: 170 * If this function returns successfully the method 171 * @FT_Incremental_FreeGlyphDataFunc will be called later to release 172 * the data bytes. 173 * 174 * Nested calls to @FT_Incremental_GetGlyphDataFunc can happen for 175 * compound glyphs. 176 * 177 */ 178 typedef FT_Error 179 (*FT_Incremental_GetGlyphDataFunc)( FT_Incremental incremental, 180 FT_UInt glyph_index, 181 FT_Data* adata ); 182 183 184 /*************************************************************************** 185 * 186 * @type: 187 * FT_Incremental_FreeGlyphDataFunc 188 * 189 * @description: 190 * A function used to release the glyph data bytes returned by a 191 * successful call to @FT_Incremental_GetGlyphDataFunc. 192 * 193 * @input: 194 * incremental :: 195 * A handle to an opaque @FT_Incremental handle provided by the client 196 * application. 197 * 198 * data :: 199 * A structure describing the glyph data bytes (which will be accessed 200 * as a read-only byte block). 201 * 202 */ 203 typedef void 204 (*FT_Incremental_FreeGlyphDataFunc)( FT_Incremental incremental, 205 FT_Data* data ); 206 207 208 /*************************************************************************** 209 * 210 * @type: 211 * FT_Incremental_GetGlyphMetricsFunc 212 * 213 * @description: 214 * A function used to retrieve the basic metrics of a given glyph index 215 * before accessing its data. This is necessary because, in certain 216 * formats like TrueType, the metrics are stored in a different place from 217 * the glyph images proper. 218 * 219 * @input: 220 * incremental :: 221 * A handle to an opaque @FT_Incremental handle provided by the client 222 * application. 223 * 224 * glyph_index :: 225 * Index of relevant glyph. 226 * 227 * vertical :: 228 * If true, return vertical metrics. 229 * 230 * ametrics :: 231 * This parameter is used for both input and output. 232 * The original glyph metrics, if any, in font units. If metrics are 233 * not available all the values must be set to zero. 234 * 235 * @output: 236 * ametrics :: 237 * The replacement glyph metrics in font units. 238 * 239 */ 240 typedef FT_Error 241 (*FT_Incremental_GetGlyphMetricsFunc) 242 ( FT_Incremental incremental, 243 FT_UInt glyph_index, 244 FT_Bool vertical, 245 FT_Incremental_MetricsRec *ametrics ); 246 247 248 /************************************************************************** 249 * 250 * @struct: 251 * FT_Incremental_FuncsRec 252 * 253 * @description: 254 * A table of functions for accessing fonts that load data 255 * incrementally. Used in @FT_Incremental_InterfaceRec. 256 * 257 * @fields: 258 * get_glyph_data :: 259 * The function to get glyph data. Must not be null. 260 * 261 * free_glyph_data :: 262 * The function to release glyph data. Must not be null. 263 * 264 * get_glyph_metrics :: 265 * The function to get glyph metrics. May be null if the font does 266 * not provide overriding glyph metrics. 267 * 268 */ 269 typedef struct FT_Incremental_FuncsRec_ 270 { 271 FT_Incremental_GetGlyphDataFunc get_glyph_data; 272 FT_Incremental_FreeGlyphDataFunc free_glyph_data; 273 FT_Incremental_GetGlyphMetricsFunc get_glyph_metrics; 274 275 } FT_Incremental_FuncsRec; 276 277 278 /*************************************************************************** 279 * 280 * @struct: 281 * FT_Incremental_InterfaceRec 282 * 283 * @description: 284 * A structure to be used with @FT_Open_Face to indicate that the user 285 * wants to support incremental glyph loading. You should use it with 286 * @FT_PARAM_TAG_INCREMENTAL as in the following example: 287 * 288 * { 289 * FT_Incremental_InterfaceRec inc_int; 290 * FT_Parameter parameter; 291 * FT_Open_Args open_args; 292 * 293 * 294 * // set up incremental descriptor 295 * inc_int.funcs = my_funcs; 296 * inc_int.object = my_object; 297 * 298 * // set up optional parameter 299 * parameter.tag = FT_PARAM_TAG_INCREMENTAL; 300 * parameter.data = &inc_int; 301 * 302 * // set up FT_Open_Args structure 303 * open_args.flags = FT_OPEN_PATHNAME | FT_OPEN_PARAMS; 304 * open_args.pathname = my_font_pathname; 305 * open_args.num_params = 1; 306 * open_args.params = ¶meter; // we use one optional argument 307 * 308 * // open the font 309 * error = FT_Open_Face( library, &open_args, index, &face ); 310 * ... 311 * } 312 * 313 */ 314 typedef struct FT_Incremental_InterfaceRec_ 315 { 316 const FT_Incremental_FuncsRec* funcs; 317 FT_Incremental object; 318 319 } FT_Incremental_InterfaceRec; 320 321 322 /*************************************************************************** 323 * 324 * @type: 325 * FT_Incremental_Interface 326 * 327 * @description: 328 * A pointer to an @FT_Incremental_InterfaceRec structure. 329 * 330 */ 331 typedef FT_Incremental_InterfaceRec* FT_Incremental_Interface; 332 333 334 /*************************************************************************** 335 * 336 * @constant: 337 * FT_PARAM_TAG_INCREMENTAL 338 * 339 * @description: 340 * A constant used as the tag of @FT_Parameter structures to indicate 341 * an incremental loading object to be used by FreeType. 342 * 343 */ 344 #define FT_PARAM_TAG_INCREMENTAL FT_MAKE_TAG( 'i', 'n', 'c', 'r' ) 345 346 /* */ 347 348 FT_END_HEADER 349 350 #endif /* __FTINCREM_H__ */ 351 352 353 /* END */ 354