source: trunk/poppler/freetype-2.2.1/include/freetype/ftincrem.h @ 150

Last change on this file since 150 was 150, checked in by Eugene Romanenko, 15 years ago

update freetype to 2.2.1

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