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