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