ftincrem.h (10696B)
1 /**************************************************************************** 2 * 3 * ftincrem.h 4 * 5 * FreeType incremental loading (specification). 6 * 7 * Copyright (C) 2002-2025 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 <freetype/freetype.h> 23 #include <freetype/ftparams.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 71 * interpreters), where the glyph data isn't in the font file, or must be 72 * overridden by different values. 73 * 74 * @note: 75 * It is up to client applications to create and implement 76 * @FT_Incremental objects, as long as they provide implementations for 77 * the methods @FT_Incremental_GetGlyphDataFunc, 78 * @FT_Incremental_FreeGlyphDataFunc and 79 * @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 by 95 * 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 the 173 * 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 allows for handling font types such 217 * as PCL~XL Format~1, Class~2 downloaded TrueType fonts, where the glyph 218 * metrics (`hmtx` and `vmtx` tables) are permitted to be omitted from 219 * the font, and the relevant metrics included in the header of the glyph 220 * outline data. Importantly, this is not intended to allow custom glyph 221 * metrics (for example, Postscript Metrics dictionaries), because that 222 * conflicts with the requirements of outline hinting. Such custom 223 * metrics must be handled separately, by the calling application. 224 * 225 * @input: 226 * incremental :: 227 * A handle to an opaque @FT_Incremental handle provided by the client 228 * application. 229 * 230 * glyph_index :: 231 * Index of relevant glyph. 232 * 233 * vertical :: 234 * If true, return vertical metrics. 235 * 236 * ametrics :: 237 * This parameter is used for both input and output. The original 238 * glyph metrics, if any, in font units. If metrics are not available 239 * all the values must be set to zero. 240 * 241 * @output: 242 * ametrics :: 243 * The glyph metrics in font units. 244 * 245 */ 246 typedef FT_Error 247 (*FT_Incremental_GetGlyphMetricsFunc) 248 ( FT_Incremental incremental, 249 FT_UInt glyph_index, 250 FT_Bool vertical, 251 FT_Incremental_MetricsRec *ametrics ); 252 253 254 /************************************************************************** 255 * 256 * @struct: 257 * FT_Incremental_FuncsRec 258 * 259 * @description: 260 * A table of functions for accessing fonts that load data incrementally. 261 * Used in @FT_Incremental_InterfaceRec. 262 * 263 * @fields: 264 * get_glyph_data :: 265 * The function to get glyph data. Must not be null. 266 * 267 * free_glyph_data :: 268 * The function to release glyph data. Must not be null. 269 * 270 * get_glyph_metrics :: 271 * The function to get glyph metrics. May be null if the font does not 272 * require it. 273 * 274 */ 275 typedef struct FT_Incremental_FuncsRec_ 276 { 277 FT_Incremental_GetGlyphDataFunc get_glyph_data; 278 FT_Incremental_FreeGlyphDataFunc free_glyph_data; 279 FT_Incremental_GetGlyphMetricsFunc get_glyph_metrics; 280 281 } FT_Incremental_FuncsRec; 282 283 284 /************************************************************************** 285 * 286 * @struct: 287 * FT_Incremental_InterfaceRec 288 * 289 * @description: 290 * A structure to be used with @FT_Open_Face to indicate that the user 291 * wants to support incremental glyph loading. You should use it with 292 * @FT_PARAM_TAG_INCREMENTAL as in the following example: 293 * 294 * ``` 295 * FT_Incremental_InterfaceRec inc_int; 296 * FT_Parameter parameter; 297 * FT_Open_Args open_args; 298 * 299 * 300 * // set up incremental descriptor 301 * inc_int.funcs = my_funcs; 302 * inc_int.object = my_object; 303 * 304 * // set up optional parameter 305 * parameter.tag = FT_PARAM_TAG_INCREMENTAL; 306 * parameter.data = &inc_int; 307 * 308 * // set up FT_Open_Args structure 309 * open_args.flags = FT_OPEN_PATHNAME | FT_OPEN_PARAMS; 310 * open_args.pathname = my_font_pathname; 311 * open_args.num_params = 1; 312 * open_args.params = ¶meter; // we use one optional argument 313 * 314 * // open the font 315 * error = FT_Open_Face( library, &open_args, index, &face ); 316 * ... 317 * ``` 318 * 319 */ 320 typedef struct FT_Incremental_InterfaceRec_ 321 { 322 const FT_Incremental_FuncsRec* funcs; 323 FT_Incremental object; 324 325 } FT_Incremental_InterfaceRec; 326 327 328 /************************************************************************** 329 * 330 * @type: 331 * FT_Incremental_Interface 332 * 333 * @description: 334 * A pointer to an @FT_Incremental_InterfaceRec structure. 335 * 336 */ 337 typedef FT_Incremental_InterfaceRec* FT_Incremental_Interface; 338 339 340 /* */ 341 342 343 FT_END_HEADER 344 345 #endif /* FTINCREM_H_ */ 346 347 348 /* END */