Set the freetype options missing in the recent update.
[pdfium.git] / third_party / freetype / include / ftincrem.h
1 /***************************************************************************/
2 /*                                                                         */
3 /*  ftincrem.h                                                             */
4 /*                                                                         */
5 /*    FreeType incremental loading (specification).                        */
6 /*                                                                         */
7 /*  Copyright 2002, 2003, 2006-2008, 2010, 2014 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
32 FT_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
348
349 FT_END_HEADER
350
351 #endif /* __FTINCREM_H__ */
352
353
354 /* END */