00001 /***************************************************************************/ 00002 /* */ 00003 /* ftincrem.h */ 00004 /* */ 00005 /* FreeType incremental loading (specification). */ 00006 /* */ 00007 /* Copyright 2002, 2003, 2006, 2007, 2008, 2010 by */ 00008 /* David Turner, Robert Wilhelm, and Werner Lemberg. */ 00009 /* */ 00010 /* This file is part of the FreeType project, and may only be used, */ 00011 /* modified, and distributed under the terms of the FreeType project */ 00012 /* license, LICENSE.TXT. By continuing to use, modify, or distribute */ 00013 /* this file you indicate that you have read the license and */ 00014 /* understand and accept it fully. */ 00015 /* */ 00016 /***************************************************************************/ 00017 00018 00019 #ifndef __FTINCREM_H__ 00020 #define __FTINCREM_H__ 00021 00022 #include <ft2build.h> 00023 #include FT_FREETYPE_H 00024 00025 #ifdef FREETYPE_H 00026 #error "freetype.h of FreeType 1 has been loaded!" 00027 #error "Please fix the directory search order for header files" 00028 #error "so that freetype.h of FreeType 2 is found first." 00029 #endif 00030 00031 00032 FT_BEGIN_HEADER 00033 00034 /*************************************************************************** 00035 * 00036 * @section: 00037 * incremental 00038 * 00039 * @title: 00040 * Incremental Loading 00041 * 00042 * @abstract: 00043 * Custom Glyph Loading. 00044 * 00045 * @description: 00046 * This section contains various functions used to perform so-called 00047 * `incremental' glyph loading. This is a mode where all glyphs loaded 00048 * from a given @FT_Face are provided by the client application, 00049 * 00050 * Apart from that, all other tables are loaded normally from the font 00051 * file. This mode is useful when FreeType is used within another 00052 * engine, e.g., a PostScript Imaging Processor. 00053 * 00054 * To enable this mode, you must use @FT_Open_Face, passing an 00055 * @FT_Parameter with the @FT_PARAM_TAG_INCREMENTAL tag and an 00056 * @FT_Incremental_Interface value. See the comments for 00057 * @FT_Incremental_InterfaceRec for an example. 00058 * 00059 */ 00060 00061 00062 /*************************************************************************** 00063 * 00064 * @type: 00065 * FT_Incremental 00066 * 00067 * @description: 00068 * An opaque type describing a user-provided object used to implement 00069 * `incremental' glyph loading within FreeType. This is used to support 00070 * embedded fonts in certain environments (e.g., PostScript interpreters), 00071 * where the glyph data isn't in the font file, or must be overridden by 00072 * different values. 00073 * 00074 * @note: 00075 * It is up to client applications to create and implement @FT_Incremental 00076 * objects, as long as they provide implementations for the methods 00077 * @FT_Incremental_GetGlyphDataFunc, @FT_Incremental_FreeGlyphDataFunc 00078 * and @FT_Incremental_GetGlyphMetricsFunc. 00079 * 00080 * See the description of @FT_Incremental_InterfaceRec to understand how 00081 * to use incremental objects with FreeType. 00082 * 00083 */ 00084 typedef struct FT_IncrementalRec_* FT_Incremental; 00085 00086 00087 /*************************************************************************** 00088 * 00089 * @struct: 00090 * FT_Incremental_MetricsRec 00091 * 00092 * @description: 00093 * A small structure used to contain the basic glyph metrics returned 00094 * by the @FT_Incremental_GetGlyphMetricsFunc method. 00095 * 00096 * @fields: 00097 * bearing_x :: 00098 * Left bearing, in font units. 00099 * 00100 * bearing_y :: 00101 * Top bearing, in font units. 00102 * 00103 * advance :: 00104 * Horizontal component of glyph advance, in font units. 00105 * 00106 * advance_v :: 00107 * Vertical component of glyph advance, in font units. 00108 * 00109 * @note: 00110 * These correspond to horizontal or vertical metrics depending on the 00111 * value of the `vertical' argument to the function 00112 * @FT_Incremental_GetGlyphMetricsFunc. 00113 * 00114 */ 00115 typedef struct FT_Incremental_MetricsRec_ 00116 { 00117 FT_Long bearing_x; 00118 FT_Long bearing_y; 00119 FT_Long advance; 00120 FT_Long advance_v; /* since 2.3.12 */ 00121 00122 } FT_Incremental_MetricsRec; 00123 00124 00125 /*************************************************************************** 00126 * 00127 * @struct: 00128 * FT_Incremental_Metrics 00129 * 00130 * @description: 00131 * A handle to an @FT_Incremental_MetricsRec structure. 00132 * 00133 */ 00134 typedef struct FT_Incremental_MetricsRec_* FT_Incremental_Metrics; 00135 00136 00137 /*************************************************************************** 00138 * 00139 * @type: 00140 * FT_Incremental_GetGlyphDataFunc 00141 * 00142 * @description: 00143 * A function called by FreeType to access a given glyph's data bytes 00144 * during @FT_Load_Glyph or @FT_Load_Char if incremental loading is 00145 * enabled. 00146 * 00147 * Note that the format of the glyph's data bytes depends on the font 00148 * file format. For TrueType, it must correspond to the raw bytes within 00149 * the `glyf' table. For PostScript formats, it must correspond to the 00150 * *unencrypted* charstring bytes, without any `lenIV' header. It is 00151 * undefined for any other format. 00152 * 00153 * @input: 00154 * incremental :: 00155 * Handle to an opaque @FT_Incremental handle provided by the client 00156 * application. 00157 * 00158 * glyph_index :: 00159 * Index of relevant glyph. 00160 * 00161 * @output: 00162 * adata :: 00163 * A structure describing the returned glyph data bytes (which will be 00164 * accessed as a read-only byte block). 00165 * 00166 * @return: 00167 * FreeType error code. 0~means success. 00168 * 00169 * @note: 00170 * If this function returns successfully the method 00171 * @FT_Incremental_FreeGlyphDataFunc will be called later to release 00172 * the data bytes. 00173 * 00174 * Nested calls to @FT_Incremental_GetGlyphDataFunc can happen for 00175 * compound glyphs. 00176 * 00177 */ 00178 typedef FT_Error 00179 (*FT_Incremental_GetGlyphDataFunc)( FT_Incremental incremental, 00180 FT_UInt glyph_index, 00181 FT_Data* adata ); 00182 00183 00184 /*************************************************************************** 00185 * 00186 * @type: 00187 * FT_Incremental_FreeGlyphDataFunc 00188 * 00189 * @description: 00190 * A function used to release the glyph data bytes returned by a 00191 * successful call to @FT_Incremental_GetGlyphDataFunc. 00192 * 00193 * @input: 00194 * incremental :: 00195 * A handle to an opaque @FT_Incremental handle provided by the client 00196 * application. 00197 * 00198 * data :: 00199 * A structure describing the glyph data bytes (which will be accessed 00200 * as a read-only byte block). 00201 * 00202 */ 00203 typedef void 00204 (*FT_Incremental_FreeGlyphDataFunc)( FT_Incremental incremental, 00205 FT_Data* data ); 00206 00207 00208 /*************************************************************************** 00209 * 00210 * @type: 00211 * FT_Incremental_GetGlyphMetricsFunc 00212 * 00213 * @description: 00214 * A function used to retrieve the basic metrics of a given glyph index 00215 * before accessing its data. This is necessary because, in certain 00216 * formats like TrueType, the metrics are stored in a different place from 00217 * the glyph images proper. 00218 * 00219 * @input: 00220 * incremental :: 00221 * A handle to an opaque @FT_Incremental handle provided by the client 00222 * application. 00223 * 00224 * glyph_index :: 00225 * Index of relevant glyph. 00226 * 00227 * vertical :: 00228 * If true, return vertical metrics. 00229 * 00230 * ametrics :: 00231 * This parameter is used for both input and output. 00232 * The original glyph metrics, if any, in font units. If metrics are 00233 * not available all the values must be set to zero. 00234 * 00235 * @output: 00236 * ametrics :: 00237 * The replacement glyph metrics in font units. 00238 * 00239 */ 00240 typedef FT_Error 00241 (*FT_Incremental_GetGlyphMetricsFunc) 00242 ( FT_Incremental incremental, 00243 FT_UInt glyph_index, 00244 FT_Bool vertical, 00245 FT_Incremental_MetricsRec *ametrics ); 00246 00247 00248 /************************************************************************** 00249 * 00250 * @struct: 00251 * FT_Incremental_FuncsRec 00252 * 00253 * @description: 00254 * A table of functions for accessing fonts that load data 00255 * incrementally. Used in @FT_Incremental_InterfaceRec. 00256 * 00257 * @fields: 00258 * get_glyph_data :: 00259 * The function to get glyph data. Must not be null. 00260 * 00261 * free_glyph_data :: 00262 * The function to release glyph data. Must not be null. 00263 * 00264 * get_glyph_metrics :: 00265 * The function to get glyph metrics. May be null if the font does 00266 * not provide overriding glyph metrics. 00267 * 00268 */ 00269 typedef struct FT_Incremental_FuncsRec_ 00270 { 00271 FT_Incremental_GetGlyphDataFunc get_glyph_data; 00272 FT_Incremental_FreeGlyphDataFunc free_glyph_data; 00273 FT_Incremental_GetGlyphMetricsFunc get_glyph_metrics; 00274 00275 } FT_Incremental_FuncsRec; 00276 00277 00278 /*************************************************************************** 00279 * 00280 * @struct: 00281 * FT_Incremental_InterfaceRec 00282 * 00283 * @description: 00284 * A structure to be used with @FT_Open_Face to indicate that the user 00285 * wants to support incremental glyph loading. You should use it with 00286 * @FT_PARAM_TAG_INCREMENTAL as in the following example: 00287 * 00288 * { 00289 * FT_Incremental_InterfaceRec inc_int; 00290 * FT_Parameter parameter; 00291 * FT_Open_Args open_args; 00292 * 00293 * 00294 * // set up incremental descriptor 00295 * inc_int.funcs = my_funcs; 00296 * inc_int.object = my_object; 00297 * 00298 * // set up optional parameter 00299 * parameter.tag = FT_PARAM_TAG_INCREMENTAL; 00300 * parameter.data = &inc_int; 00301 * 00302 * // set up FT_Open_Args structure 00303 * open_args.flags = FT_OPEN_PATHNAME | FT_OPEN_PARAMS; 00304 * open_args.pathname = my_font_pathname; 00305 * open_args.num_params = 1; 00306 * open_args.params = ¶meter; // we use one optional argument 00307 * 00308 * // open the font 00309 * error = FT_Open_Face( library, &open_args, index, &face ); 00310 * ... 00311 * } 00312 * 00313 */ 00314 typedef struct FT_Incremental_InterfaceRec_ 00315 { 00316 const FT_Incremental_FuncsRec* funcs; 00317 FT_Incremental object; 00318 00319 } FT_Incremental_InterfaceRec; 00320 00321 00322 /*************************************************************************** 00323 * 00324 * @type: 00325 * FT_Incremental_Interface 00326 * 00327 * @description: 00328 * A pointer to an @FT_Incremental_InterfaceRec structure. 00329 * 00330 */ 00331 typedef FT_Incremental_InterfaceRec* FT_Incremental_Interface; 00332 00333 00334 /*************************************************************************** 00335 * 00336 * @constant: 00337 * FT_PARAM_TAG_INCREMENTAL 00338 * 00339 * @description: 00340 * A constant used as the tag of @FT_Parameter structures to indicate 00341 * an incremental loading object to be used by FreeType. 00342 * 00343 */ 00344 #define FT_PARAM_TAG_INCREMENTAL FT_MAKE_TAG( 'i', 'n', 'c', 'r' ) 00345 00346 /* */ 00347 00348 FT_END_HEADER 00349 00350 #endif /* __FTINCREM_H__ */ 00351 00352 00353 /* END */
1.5.1