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