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 */ | 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 */ |