The Tor Browser / annotate

modules/freetype2/include/ftincrem.h@b8a032363ba2 (annotated)

modules/freetype2/include/ftincrem.h

Thu, 22 Jan 2015 13:21:57 +0100

author
Michael Schloh von Bennewitz <michael@schloh.com>
date
Thu, 22 Jan 2015 13:21:57 +0100
branch
TOR_BUG_9701
changeset 15
b8a032363ba2
permissions
-rw-r--r--

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

michael@0 1 /***************************************************************************/
michael@0 2 /* */
michael@0 3 /* ftincrem.h */
michael@0 4 /* */
michael@0 5 /* FreeType incremental loading (specification). */
michael@0 6 /* */
michael@0 7 /* Copyright 2002, 2003, 2006, 2007, 2008, 2010 by */
michael@0 8 /* David Turner, Robert Wilhelm, and Werner Lemberg. */
michael@0 9 /* */
michael@0 10 /* This file is part of the FreeType project, and may only be used, */
michael@0 11 /* modified, and distributed under the terms of the FreeType project */
michael@0 12 /* license, LICENSE.TXT. By continuing to use, modify, or distribute */
michael@0 13 /* this file you indicate that you have read the license and */
michael@0 14 /* understand and accept it fully. */
michael@0 15 /* */
michael@0 16 /***************************************************************************/
michael@0 17
michael@0 18
michael@0 19 #ifndef __FTINCREM_H__
michael@0 20 #define __FTINCREM_H__
michael@0 21
michael@0 22 #include <ft2build.h>
michael@0 23 #include FT_FREETYPE_H
michael@0 24
michael@0 25 #ifdef FREETYPE_H
michael@0 26 #error "freetype.h of FreeType 1 has been loaded!"
michael@0 27 #error "Please fix the directory search order for header files"
michael@0 28 #error "so that freetype.h of FreeType 2 is found first."
michael@0 29 #endif
michael@0 30
michael@0 31
michael@0 32 FT_BEGIN_HEADER
michael@0 33
michael@0 34 /***************************************************************************
michael@0 35 *
michael@0 36 * @section:
michael@0 37 * incremental
michael@0 38 *
michael@0 39 * @title:
michael@0 40 * Incremental Loading
michael@0 41 *
michael@0 42 * @abstract:
michael@0 43 * Custom Glyph Loading.
michael@0 44 *
michael@0 45 * @description:
michael@0 46 * This section contains various functions used to perform so-called
michael@0 47 * `incremental' glyph loading. This is a mode where all glyphs loaded
michael@0 48 * from a given @FT_Face are provided by the client application,
michael@0 49 *
michael@0 50 * Apart from that, all other tables are loaded normally from the font
michael@0 51 * file. This mode is useful when FreeType is used within another
michael@0 52 * engine, e.g., a PostScript Imaging Processor.
michael@0 53 *
michael@0 54 * To enable this mode, you must use @FT_Open_Face, passing an
michael@0 55 * @FT_Parameter with the @FT_PARAM_TAG_INCREMENTAL tag and an
michael@0 56 * @FT_Incremental_Interface value. See the comments for
michael@0 57 * @FT_Incremental_InterfaceRec for an example.
michael@0 58 *
michael@0 59 */
michael@0 60
michael@0 61
michael@0 62 /***************************************************************************
michael@0 63 *
michael@0 64 * @type:
michael@0 65 * FT_Incremental
michael@0 66 *
michael@0 67 * @description:
michael@0 68 * An opaque type describing a user-provided object used to implement
michael@0 69 * `incremental' glyph loading within FreeType. This is used to support
michael@0 70 * embedded fonts in certain environments (e.g., PostScript interpreters),
michael@0 71 * where the glyph data isn't in the font file, or must be overridden by
michael@0 72 * different values.
michael@0 73 *
michael@0 74 * @note:
michael@0 75 * It is up to client applications to create and implement @FT_Incremental
michael@0 76 * objects, as long as they provide implementations for the methods
michael@0 77 * @FT_Incremental_GetGlyphDataFunc, @FT_Incremental_FreeGlyphDataFunc
michael@0 78 * and @FT_Incremental_GetGlyphMetricsFunc.
michael@0 79 *
michael@0 80 * See the description of @FT_Incremental_InterfaceRec to understand how
michael@0 81 * to use incremental objects with FreeType.
michael@0 82 *
michael@0 83 */
michael@0 84 typedef struct FT_IncrementalRec_* FT_Incremental;
michael@0 85
michael@0 86
michael@0 87 /***************************************************************************
michael@0 88 *
michael@0 89 * @struct:
michael@0 90 * FT_Incremental_MetricsRec
michael@0 91 *
michael@0 92 * @description:
michael@0 93 * A small structure used to contain the basic glyph metrics returned
michael@0 94 * by the @FT_Incremental_GetGlyphMetricsFunc method.
michael@0 95 *
michael@0 96 * @fields:
michael@0 97 * bearing_x ::
michael@0 98 * Left bearing, in font units.
michael@0 99 *
michael@0 100 * bearing_y ::
michael@0 101 * Top bearing, in font units.
michael@0 102 *
michael@0 103 * advance ::
michael@0 104 * Horizontal component of glyph advance, in font units.
michael@0 105 *
michael@0 106 * advance_v ::
michael@0 107 * Vertical component of glyph advance, in font units.
michael@0 108 *
michael@0 109 * @note:
michael@0 110 * These correspond to horizontal or vertical metrics depending on the
michael@0 111 * value of the `vertical' argument to the function
michael@0 112 * @FT_Incremental_GetGlyphMetricsFunc.
michael@0 113 *
michael@0 114 */
michael@0 115 typedef struct FT_Incremental_MetricsRec_
michael@0 116 {
michael@0 117 FT_Long bearing_x;
michael@0 118 FT_Long bearing_y;
michael@0 119 FT_Long advance;
michael@0 120 FT_Long advance_v; /* since 2.3.12 */
michael@0 121
michael@0 122 } FT_Incremental_MetricsRec;
michael@0 123
michael@0 124
michael@0 125 /***************************************************************************
michael@0 126 *
michael@0 127 * @struct:
michael@0 128 * FT_Incremental_Metrics
michael@0 129 *
michael@0 130 * @description:
michael@0 131 * A handle to an @FT_Incremental_MetricsRec structure.
michael@0 132 *
michael@0 133 */
michael@0 134 typedef struct FT_Incremental_MetricsRec_* FT_Incremental_Metrics;
michael@0 135
michael@0 136
michael@0 137 /***************************************************************************
michael@0 138 *
michael@0 139 * @type:
michael@0 140 * FT_Incremental_GetGlyphDataFunc
michael@0 141 *
michael@0 142 * @description:
michael@0 143 * A function called by FreeType to access a given glyph's data bytes
michael@0 144 * during @FT_Load_Glyph or @FT_Load_Char if incremental loading is
michael@0 145 * enabled.
michael@0 146 *
michael@0 147 * Note that the format of the glyph's data bytes depends on the font
michael@0 148 * file format. For TrueType, it must correspond to the raw bytes within
michael@0 149 * the `glyf' table. For PostScript formats, it must correspond to the
michael@0 150 * *unencrypted* charstring bytes, without any `lenIV' header. It is
michael@0 151 * undefined for any other format.
michael@0 152 *
michael@0 153 * @input:
michael@0 154 * incremental ::
michael@0 155 * Handle to an opaque @FT_Incremental handle provided by the client
michael@0 156 * application.
michael@0 157 *
michael@0 158 * glyph_index ::
michael@0 159 * Index of relevant glyph.
michael@0 160 *
michael@0 161 * @output:
michael@0 162 * adata ::
michael@0 163 * A structure describing the returned glyph data bytes (which will be
michael@0 164 * accessed as a read-only byte block).
michael@0 165 *
michael@0 166 * @return:
michael@0 167 * FreeType error code. 0~means success.
michael@0 168 *
michael@0 169 * @note:
michael@0 170 * If this function returns successfully the method
michael@0 171 * @FT_Incremental_FreeGlyphDataFunc will be called later to release
michael@0 172 * the data bytes.
michael@0 173 *
michael@0 174 * Nested calls to @FT_Incremental_GetGlyphDataFunc can happen for
michael@0 175 * compound glyphs.
michael@0 176 *
michael@0 177 */
michael@0 178 typedef FT_Error
michael@0 179 (*FT_Incremental_GetGlyphDataFunc)( FT_Incremental incremental,
michael@0 180 FT_UInt glyph_index,
michael@0 181 FT_Data* adata );
michael@0 182
michael@0 183
michael@0 184 /***************************************************************************
michael@0 185 *
michael@0 186 * @type:
michael@0 187 * FT_Incremental_FreeGlyphDataFunc
michael@0 188 *
michael@0 189 * @description:
michael@0 190 * A function used to release the glyph data bytes returned by a
michael@0 191 * successful call to @FT_Incremental_GetGlyphDataFunc.
michael@0 192 *
michael@0 193 * @input:
michael@0 194 * incremental ::
michael@0 195 * A handle to an opaque @FT_Incremental handle provided by the client
michael@0 196 * application.
michael@0 197 *
michael@0 198 * data ::
michael@0 199 * A structure describing the glyph data bytes (which will be accessed
michael@0 200 * as a read-only byte block).
michael@0 201 *
michael@0 202 */
michael@0 203 typedef void
michael@0 204 (*FT_Incremental_FreeGlyphDataFunc)( FT_Incremental incremental,
michael@0 205 FT_Data* data );
michael@0 206
michael@0 207
michael@0 208 /***************************************************************************
michael@0 209 *
michael@0 210 * @type:
michael@0 211 * FT_Incremental_GetGlyphMetricsFunc
michael@0 212 *
michael@0 213 * @description:
michael@0 214 * A function used to retrieve the basic metrics of a given glyph index
michael@0 215 * before accessing its data. This is necessary because, in certain
michael@0 216 * formats like TrueType, the metrics are stored in a different place from
michael@0 217 * the glyph images proper.
michael@0 218 *
michael@0 219 * @input:
michael@0 220 * incremental ::
michael@0 221 * A handle to an opaque @FT_Incremental handle provided by the client
michael@0 222 * application.
michael@0 223 *
michael@0 224 * glyph_index ::
michael@0 225 * Index of relevant glyph.
michael@0 226 *
michael@0 227 * vertical ::
michael@0 228 * If true, return vertical metrics.
michael@0 229 *
michael@0 230 * ametrics ::
michael@0 231 * This parameter is used for both input and output.
michael@0 232 * The original glyph metrics, if any, in font units. If metrics are
michael@0 233 * not available all the values must be set to zero.
michael@0 234 *
michael@0 235 * @output:
michael@0 236 * ametrics ::
michael@0 237 * The replacement glyph metrics in font units.
michael@0 238 *
michael@0 239 */
michael@0 240 typedef FT_Error
michael@0 241 (*FT_Incremental_GetGlyphMetricsFunc)
michael@0 242 ( FT_Incremental incremental,
michael@0 243 FT_UInt glyph_index,
michael@0 244 FT_Bool vertical,
michael@0 245 FT_Incremental_MetricsRec *ametrics );
michael@0 246
michael@0 247
michael@0 248 /**************************************************************************
michael@0 249 *
michael@0 250 * @struct:
michael@0 251 * FT_Incremental_FuncsRec
michael@0 252 *
michael@0 253 * @description:
michael@0 254 * A table of functions for accessing fonts that load data
michael@0 255 * incrementally. Used in @FT_Incremental_InterfaceRec.
michael@0 256 *
michael@0 257 * @fields:
michael@0 258 * get_glyph_data ::
michael@0 259 * The function to get glyph data. Must not be null.
michael@0 260 *
michael@0 261 * free_glyph_data ::
michael@0 262 * The function to release glyph data. Must not be null.
michael@0 263 *
michael@0 264 * get_glyph_metrics ::
michael@0 265 * The function to get glyph metrics. May be null if the font does
michael@0 266 * not provide overriding glyph metrics.
michael@0 267 *
michael@0 268 */
michael@0 269 typedef struct FT_Incremental_FuncsRec_
michael@0 270 {
michael@0 271 FT_Incremental_GetGlyphDataFunc get_glyph_data;
michael@0 272 FT_Incremental_FreeGlyphDataFunc free_glyph_data;
michael@0 273 FT_Incremental_GetGlyphMetricsFunc get_glyph_metrics;
michael@0 274
michael@0 275 } FT_Incremental_FuncsRec;
michael@0 276
michael@0 277
michael@0 278 /***************************************************************************
michael@0 279 *
michael@0 280 * @struct:
michael@0 281 * FT_Incremental_InterfaceRec
michael@0 282 *
michael@0 283 * @description:
michael@0 284 * A structure to be used with @FT_Open_Face to indicate that the user
michael@0 285 * wants to support incremental glyph loading. You should use it with
michael@0 286 * @FT_PARAM_TAG_INCREMENTAL as in the following example:
michael@0 287 *
michael@0 288 * {
michael@0 289 * FT_Incremental_InterfaceRec inc_int;
michael@0 290 * FT_Parameter parameter;
michael@0 291 * FT_Open_Args open_args;
michael@0 292 *
michael@0 293 *
michael@0 294 * // set up incremental descriptor
michael@0 295 * inc_int.funcs = my_funcs;
michael@0 296 * inc_int.object = my_object;
michael@0 297 *
michael@0 298 * // set up optional parameter
michael@0 299 * parameter.tag = FT_PARAM_TAG_INCREMENTAL;
michael@0 300 * parameter.data = &inc_int;
michael@0 301 *
michael@0 302 * // set up FT_Open_Args structure
michael@0 303 * open_args.flags = FT_OPEN_PATHNAME | FT_OPEN_PARAMS;
michael@0 304 * open_args.pathname = my_font_pathname;
michael@0 305 * open_args.num_params = 1;
michael@0 306 * open_args.params = &parameter; // we use one optional argument
michael@0 307 *
michael@0 308 * // open the font
michael@0 309 * error = FT_Open_Face( library, &open_args, index, &face );
michael@0 310 * ...
michael@0 311 * }
michael@0 312 *
michael@0 313 */
michael@0 314 typedef struct FT_Incremental_InterfaceRec_
michael@0 315 {
michael@0 316 const FT_Incremental_FuncsRec* funcs;
michael@0 317 FT_Incremental object;
michael@0 318
michael@0 319 } FT_Incremental_InterfaceRec;
michael@0 320
michael@0 321
michael@0 322 /***************************************************************************
michael@0 323 *
michael@0 324 * @type:
michael@0 325 * FT_Incremental_Interface
michael@0 326 *
michael@0 327 * @description:
michael@0 328 * A pointer to an @FT_Incremental_InterfaceRec structure.
michael@0 329 *
michael@0 330 */
michael@0 331 typedef FT_Incremental_InterfaceRec* FT_Incremental_Interface;
michael@0 332
michael@0 333
michael@0 334 /***************************************************************************
michael@0 335 *
michael@0 336 * @constant:
michael@0 337 * FT_PARAM_TAG_INCREMENTAL
michael@0 338 *
michael@0 339 * @description:
michael@0 340 * A constant used as the tag of @FT_Parameter structures to indicate
michael@0 341 * an incremental loading object to be used by FreeType.
michael@0 342 *
michael@0 343 */
michael@0 344 #define FT_PARAM_TAG_INCREMENTAL FT_MAKE_TAG( 'i', 'n', 'c', 'r' )
michael@0 345
michael@0 346 /* */
michael@0 347
michael@0 348 FT_END_HEADER
michael@0 349
michael@0 350 #endif /* __FTINCREM_H__ */
michael@0 351
michael@0 352
michael@0 353 /* END */

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial