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