source: trunk/poppler/freetype2/include/freetype/ftincrem.h @ 251

Last change on this file since 251 was 251, checked in by Eugene Romanenko, 13 years ago

PDF plugin: freetype library updated to version 2.3.5

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