vrshoot

annotate libs/ft2static/freetype/ftincrem.h @ 0:b2f14e535253

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