source: trunk/poppler/freetype-2.1.10/include/freetype/ftincrem.h @ 2

Last change on this file since 2 was 2, checked in by Eugene Romanenko, 16 years ago

First import

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