Add the license back to ftmodule.h after the freetype 2.5.4 upgrade.
[pdfium.git] / third_party / freetype / include / freetype.h
1 /***************************************************************************/
2 /*                                                                         */
3 /*  freetype.h                                                             */
4 /*                                                                         */
5 /*    FreeType high-level API and common types (specification only).       */
6 /*                                                                         */
7 /*  Copyright 1996-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 __FREETYPE_H__
20 #define __FREETYPE_H__
21
22
23 #ifndef FT_FREETYPE_H
24 #error "`ft2build.h' hasn't been included yet!"
25 #error "Please always use macros to include FreeType header files."
26 #error "Example:"
27 #error "  #include <ft2build.h>"
28 #error "  #include FT_FREETYPE_H"
29 #endif
30
31
32 #include <ft2build.h>
33 #include FT_CONFIG_CONFIG_H
34 #include FT_TYPES_H
35 #include FT_ERRORS_H
36
37
38 FT_BEGIN_HEADER
39
40
41
42   /*************************************************************************/
43   /*                                                                       */
44   /* <Section>                                                             */
45   /*    header_inclusion                                                   */
46   /*                                                                       */
47   /* <Title>                                                               */
48   /*    FreeType's header inclusion scheme                                 */
49   /*                                                                       */
50   /* <Abstract>                                                            */
51   /*    How client applications should include FreeType header files.      */
52   /*                                                                       */
53   /* <Description>                                                         */
54   /*    To be as flexible as possible (and for historical reasons),        */
55   /*    FreeType uses a very special inclusion scheme to load header       */
56   /*    files, for example                                                 */
57   /*                                                                       */
58   /*    {                                                                  */
59   /*      #include <ft2build.h>                                            */
60   /*                                                                       */
61   /*      #include FT_FREETYPE_H                                           */
62   /*      #include FT_OUTLINE_H                                            */
63   /*    }                                                                  */
64   /*                                                                       */
65   /*    A compiler and its preprocessor only needs an include path to find */
66   /*    the file `ft2build.h'; the exact locations and names of the other  */
67   /*    FreeType header files are hidden by preprocessor macro names,      */
68   /*    loaded by `ft2build.h'.  The API documentation always gives the    */
69   /*    header macro name needed for a particular function.                */
70   /*                                                                       */
71   /*************************************************************************/
72
73
74   /*************************************************************************/
75   /*                                                                       */
76   /* <Section>                                                             */
77   /*    user_allocation                                                    */
78   /*                                                                       */
79   /* <Title>                                                               */
80   /*    User allocation                                                    */
81   /*                                                                       */
82   /* <Abstract>                                                            */
83   /*    How client applications should allocate FreeType data structures.  */
84   /*                                                                       */
85   /* <Description>                                                         */
86   /*    FreeType assumes that structures allocated by the user and passed  */
87   /*    as arguments are zeroed out except for the actual data.  In other  */
88   /*    words, it is recommended to use `calloc' (or variants of it)       */
89   /*    instead of `malloc' for allocation.                                */
90   /*                                                                       */
91   /*************************************************************************/
92
93
94
95   /*************************************************************************/
96   /*************************************************************************/
97   /*                                                                       */
98   /*                        B A S I C   T Y P E S                          */
99   /*                                                                       */
100   /*************************************************************************/
101   /*************************************************************************/
102
103
104   /*************************************************************************/
105   /*                                                                       */
106   /* <Section>                                                             */
107   /*    base_interface                                                     */
108   /*                                                                       */
109   /* <Title>                                                               */
110   /*    Base Interface                                                     */
111   /*                                                                       */
112   /* <Abstract>                                                            */
113   /*    The FreeType~2 base font interface.                                */
114   /*                                                                       */
115   /* <Description>                                                         */
116   /*    This section describes the most important public high-level API    */
117   /*    functions of FreeType~2.                                           */
118   /*                                                                       */
119   /* <Order>                                                               */
120   /*    FT_Library                                                         */
121   /*    FT_Face                                                            */
122   /*    FT_Size                                                            */
123   /*    FT_GlyphSlot                                                       */
124   /*    FT_CharMap                                                         */
125   /*    FT_Encoding                                                        */
126   /*    FT_ENC_TAG                                                         */
127   /*                                                                       */
128   /*    FT_FaceRec                                                         */
129   /*                                                                       */
130   /*    FT_FACE_FLAG_SCALABLE                                              */
131   /*    FT_FACE_FLAG_FIXED_SIZES                                           */
132   /*    FT_FACE_FLAG_FIXED_WIDTH                                           */
133   /*    FT_FACE_FLAG_HORIZONTAL                                            */
134   /*    FT_FACE_FLAG_VERTICAL                                              */
135   /*    FT_FACE_FLAG_COLOR                                                 */
136   /*    FT_FACE_FLAG_SFNT                                                  */
137   /*    FT_FACE_FLAG_CID_KEYED                                             */
138   /*    FT_FACE_FLAG_TRICKY                                                */
139   /*    FT_FACE_FLAG_KERNING                                               */
140   /*    FT_FACE_FLAG_MULTIPLE_MASTERS                                      */
141   /*    FT_FACE_FLAG_GLYPH_NAMES                                           */
142   /*    FT_FACE_FLAG_EXTERNAL_STREAM                                       */
143   /*    FT_FACE_FLAG_HINTER                                                */
144   /*    FT_FACE_FLAG_TRICKY                                                */
145   /*                                                                       */
146   /*    FT_HAS_HORIZONTAL                                                  */
147   /*    FT_HAS_VERTICAL                                                    */
148   /*    FT_HAS_KERNING                                                     */
149   /*    FT_HAS_FIXED_SIZES                                                 */
150   /*    FT_HAS_GLYPH_NAMES                                                 */
151   /*    FT_HAS_MULTIPLE_MASTERS                                            */
152   /*    FT_HAS_COLOR                                                       */
153   /*                                                                       */
154   /*    FT_IS_SFNT                                                         */
155   /*    FT_IS_SCALABLE                                                     */
156   /*    FT_IS_FIXED_WIDTH                                                  */
157   /*    FT_IS_CID_KEYED                                                    */
158   /*    FT_IS_TRICKY                                                       */
159   /*                                                                       */
160   /*    FT_STYLE_FLAG_BOLD                                                 */
161   /*    FT_STYLE_FLAG_ITALIC                                               */
162   /*                                                                       */
163   /*    FT_SizeRec                                                         */
164   /*    FT_Size_Metrics                                                    */
165   /*                                                                       */
166   /*    FT_GlyphSlotRec                                                    */
167   /*    FT_Glyph_Metrics                                                   */
168   /*    FT_SubGlyph                                                        */
169   /*                                                                       */
170   /*    FT_Bitmap_Size                                                     */
171   /*                                                                       */
172   /*    FT_Init_FreeType                                                   */
173   /*    FT_Done_FreeType                                                   */
174   /*                                                                       */
175   /*    FT_New_Face                                                        */
176   /*    FT_Done_Face                                                       */
177   /*    FT_Reference_Face                                                  */
178   /*    FT_New_Memory_Face                                                 */
179   /*    FT_Open_Face                                                       */
180   /*    FT_Open_Args                                                       */
181   /*    FT_Parameter                                                       */
182   /*    FT_Attach_File                                                     */
183   /*    FT_Attach_Stream                                                   */
184   /*                                                                       */
185   /*    FT_Set_Char_Size                                                   */
186   /*    FT_Set_Pixel_Sizes                                                 */
187   /*    FT_Request_Size                                                    */
188   /*    FT_Select_Size                                                     */
189   /*    FT_Size_Request_Type                                               */
190   /*    FT_Size_RequestRec                                                 */
191   /*    FT_Size_Request                                                    */
192   /*    FT_Set_Transform                                                   */
193   /*    FT_Load_Glyph                                                      */
194   /*    FT_Get_Char_Index                                                  */
195   /*    FT_Get_First_Char                                                  */
196   /*    FT_Get_Next_Char                                                   */
197   /*    FT_Get_Name_Index                                                  */
198   /*    FT_Load_Char                                                       */
199   /*                                                                       */
200   /*    FT_OPEN_MEMORY                                                     */
201   /*    FT_OPEN_STREAM                                                     */
202   /*    FT_OPEN_PATHNAME                                                   */
203   /*    FT_OPEN_DRIVER                                                     */
204   /*    FT_OPEN_PARAMS                                                     */
205   /*                                                                       */
206   /*    FT_LOAD_DEFAULT                                                    */
207   /*    FT_LOAD_RENDER                                                     */
208   /*    FT_LOAD_MONOCHROME                                                 */
209   /*    FT_LOAD_LINEAR_DESIGN                                              */
210   /*    FT_LOAD_NO_SCALE                                                   */
211   /*    FT_LOAD_NO_HINTING                                                 */
212   /*    FT_LOAD_NO_BITMAP                                                  */
213   /*    FT_LOAD_NO_AUTOHINT                                                */
214   /*    FT_LOAD_COLOR                                                      */
215   /*                                                                       */
216   /*    FT_LOAD_VERTICAL_LAYOUT                                            */
217   /*    FT_LOAD_IGNORE_TRANSFORM                                           */
218   /*    FT_LOAD_FORCE_AUTOHINT                                             */
219   /*    FT_LOAD_NO_RECURSE                                                 */
220   /*    FT_LOAD_PEDANTIC                                                   */
221   /*                                                                       */
222   /*    FT_LOAD_TARGET_NORMAL                                              */
223   /*    FT_LOAD_TARGET_LIGHT                                               */
224   /*    FT_LOAD_TARGET_MONO                                                */
225   /*    FT_LOAD_TARGET_LCD                                                 */
226   /*    FT_LOAD_TARGET_LCD_V                                               */
227   /*                                                                       */
228   /*    FT_LOAD_TARGET_MODE                                                */
229   /*                                                                       */
230   /*    FT_Render_Glyph                                                    */
231   /*    FT_Render_Mode                                                     */
232   /*    FT_Get_Kerning                                                     */
233   /*    FT_Kerning_Mode                                                    */
234   /*    FT_Get_Track_Kerning                                               */
235   /*    FT_Get_Glyph_Name                                                  */
236   /*    FT_Get_Postscript_Name                                             */
237   /*                                                                       */
238   /*    FT_CharMapRec                                                      */
239   /*    FT_Select_Charmap                                                  */
240   /*    FT_Set_Charmap                                                     */
241   /*    FT_Get_Charmap_Index                                               */
242   /*                                                                       */
243   /*    FT_Get_FSType_Flags                                                */
244   /*    FT_Get_SubGlyph_Info                                               */
245   /*                                                                       */
246   /*    FT_Face_Internal                                                   */
247   /*    FT_Size_Internal                                                   */
248   /*    FT_Slot_Internal                                                   */
249   /*                                                                       */
250   /*    FT_FACE_FLAG_XXX                                                   */
251   /*    FT_STYLE_FLAG_XXX                                                  */
252   /*    FT_OPEN_XXX                                                        */
253   /*    FT_LOAD_XXX                                                        */
254   /*    FT_LOAD_TARGET_XXX                                                 */
255   /*    FT_SUBGLYPH_FLAG_XXX                                               */
256   /*    FT_FSTYPE_XXX                                                      */
257   /*                                                                       */
258   /*    FT_HAS_FAST_GLYPHS                                                 */
259   /*                                                                       */
260   /*************************************************************************/
261
262
263   /*************************************************************************/
264   /*                                                                       */
265   /* <Struct>                                                              */
266   /*    FT_Glyph_Metrics                                                   */
267   /*                                                                       */
268   /* <Description>                                                         */
269   /*    A structure used to model the metrics of a single glyph.  The      */
270   /*    values are expressed in 26.6 fractional pixel format; if the flag  */
271   /*    @FT_LOAD_NO_SCALE has been used while loading the glyph, values    */
272   /*    are expressed in font units instead.                               */
273   /*                                                                       */
274   /* <Fields>                                                              */
275   /*    width ::                                                           */
276   /*      The glyph's width.                                               */
277   /*                                                                       */
278   /*    height ::                                                          */
279   /*      The glyph's height.                                              */
280   /*                                                                       */
281   /*    horiBearingX ::                                                    */
282   /*      Left side bearing for horizontal layout.                         */
283   /*                                                                       */
284   /*    horiBearingY ::                                                    */
285   /*      Top side bearing for horizontal layout.                          */
286   /*                                                                       */
287   /*    horiAdvance ::                                                     */
288   /*      Advance width for horizontal layout.                             */
289   /*                                                                       */
290   /*    vertBearingX ::                                                    */
291   /*      Left side bearing for vertical layout.                           */
292   /*                                                                       */
293   /*    vertBearingY ::                                                    */
294   /*      Top side bearing for vertical layout.  Larger positive values    */
295   /*      mean further below the vertical glyph origin.                    */
296   /*                                                                       */
297   /*    vertAdvance ::                                                     */
298   /*      Advance height for vertical layout.  Positive values mean the    */
299   /*      glyph has a positive advance downward.                           */
300   /*                                                                       */
301   /* <Note>                                                                */
302   /*    If not disabled with @FT_LOAD_NO_HINTING, the values represent     */
303   /*    dimensions of the hinted glyph (in case hinting is applicable).    */
304   /*                                                                       */
305   /*    Stroking a glyph with an outside border does not increase          */
306   /*    `horiAdvance' or `vertAdvance'; you have to manually adjust these  */
307   /*    values to account for the added width and height.                  */
308   /*                                                                       */
309   typedef struct  FT_Glyph_Metrics_
310   {
311     FT_Pos  width;
312     FT_Pos  height;
313
314     FT_Pos  horiBearingX;
315     FT_Pos  horiBearingY;
316     FT_Pos  horiAdvance;
317
318     FT_Pos  vertBearingX;
319     FT_Pos  vertBearingY;
320     FT_Pos  vertAdvance;
321
322   } FT_Glyph_Metrics;
323
324
325   /*************************************************************************/
326   /*                                                                       */
327   /* <Struct>                                                              */
328   /*    FT_Bitmap_Size                                                     */
329   /*                                                                       */
330   /* <Description>                                                         */
331   /*    This structure models the metrics of a bitmap strike (i.e., a set  */
332   /*    of glyphs for a given point size and resolution) in a bitmap font. */
333   /*    It is used for the `available_sizes' field of @FT_Face.            */
334   /*                                                                       */
335   /* <Fields>                                                              */
336   /*    height :: The vertical distance, in pixels, between two            */
337   /*              consecutive baselines.  It is always positive.           */
338   /*                                                                       */
339   /*    width  :: The average width, in pixels, of all glyphs in the       */
340   /*              strike.                                                  */
341   /*                                                                       */
342   /*    size   :: The nominal size of the strike in 26.6 fractional        */
343   /*              points.  This field is not very useful.                  */
344   /*                                                                       */
345   /*    x_ppem :: The horizontal ppem (nominal width) in 26.6 fractional   */
346   /*              pixels.                                                  */
347   /*                                                                       */
348   /*    y_ppem :: The vertical ppem (nominal height) in 26.6 fractional    */
349   /*              pixels.                                                  */
350   /*                                                                       */
351   /* <Note>                                                                */
352   /*    Windows FNT:                                                       */
353   /*      The nominal size given in a FNT font is not reliable.  Thus when */
354   /*      the driver finds it incorrect, it sets `size' to some calculated */
355   /*      values and sets `x_ppem' and `y_ppem' to the pixel width and     */
356   /*      height given in the font, respectively.                          */
357   /*                                                                       */
358   /*    TrueType embedded bitmaps:                                         */
359   /*      `size', `width', and `height' values are not contained in the    */
360   /*      bitmap strike itself.  They are computed from the global font    */
361   /*      parameters.                                                      */
362   /*                                                                       */
363   typedef struct  FT_Bitmap_Size_
364   {
365     FT_Short  height;
366     FT_Short  width;
367
368     FT_Pos    size;
369
370     FT_Pos    x_ppem;
371     FT_Pos    y_ppem;
372
373   } FT_Bitmap_Size;
374
375
376   /*************************************************************************/
377   /*************************************************************************/
378   /*                                                                       */
379   /*                     O B J E C T   C L A S S E S                       */
380   /*                                                                       */
381   /*************************************************************************/
382   /*************************************************************************/
383
384   /*************************************************************************/
385   /*                                                                       */
386   /* <Type>                                                                */
387   /*    FT_Library                                                         */
388   /*                                                                       */
389   /* <Description>                                                         */
390   /*    A handle to a FreeType library instance.  Each `library' is        */
391   /*    completely independent from the others; it is the `root' of a set  */
392   /*    of objects like fonts, faces, sizes, etc.                          */
393   /*                                                                       */
394   /*    It also embeds a memory manager (see @FT_Memory), as well as a     */
395   /*    scan-line converter object (see @FT_Raster).                       */
396   /*                                                                       */
397   /*    In multi-threaded applications, make sure that the same FT_Library */
398   /*    object or any of its children doesn't get accessed in parallel.    */
399   /*                                                                       */
400   /* <Note>                                                                */
401   /*    Library objects are normally created by @FT_Init_FreeType, and     */
402   /*    destroyed with @FT_Done_FreeType.  If you need reference-counting  */
403   /*    (cf. @FT_Reference_Library), use @FT_New_Library and               */
404   /*    @FT_Done_Library.                                                  */
405   /*                                                                       */
406   typedef struct FT_LibraryRec_  *FT_Library;
407
408
409   /*************************************************************************/
410   /*                                                                       */
411   /* <Section>                                                             */
412   /*    module_management                                                  */
413   /*                                                                       */
414   /*************************************************************************/
415
416   /*************************************************************************/
417   /*                                                                       */
418   /* <Type>                                                                */
419   /*    FT_Module                                                          */
420   /*                                                                       */
421   /* <Description>                                                         */
422   /*    A handle to a given FreeType module object.  Each module can be a  */
423   /*    font driver, a renderer, or anything else that provides services   */
424   /*    to the formers.                                                    */
425   /*                                                                       */
426   typedef struct FT_ModuleRec_*  FT_Module;
427
428
429   /*************************************************************************/
430   /*                                                                       */
431   /* <Type>                                                                */
432   /*    FT_Driver                                                          */
433   /*                                                                       */
434   /* <Description>                                                         */
435   /*    A handle to a given FreeType font driver object.  Each font driver */
436   /*    is a special module capable of creating faces from font files.     */
437   /*                                                                       */
438   typedef struct FT_DriverRec_*  FT_Driver;
439
440
441   /*************************************************************************/
442   /*                                                                       */
443   /* <Type>                                                                */
444   /*    FT_Renderer                                                        */
445   /*                                                                       */
446   /* <Description>                                                         */
447   /*    A handle to a given FreeType renderer.  A renderer is a special    */
448   /*    module in charge of converting a glyph image to a bitmap, when     */
449   /*    necessary.  Each renderer supports a given glyph image format, and */
450   /*    one or more target surface depths.                                 */
451   /*                                                                       */
452   typedef struct FT_RendererRec_*  FT_Renderer;
453
454
455   /*************************************************************************/
456   /*                                                                       */
457   /* <Section>                                                             */
458   /*    base_interface                                                     */
459   /*                                                                       */
460   /*************************************************************************/
461
462   /*************************************************************************/
463   /*                                                                       */
464   /* <Type>                                                                */
465   /*    FT_Face                                                            */
466   /*                                                                       */
467   /* <Description>                                                         */
468   /*    A handle to a given typographic face object.  A face object models */
469   /*    a given typeface, in a given style.                                */
470   /*                                                                       */
471   /* <Note>                                                                */
472   /*    Each face object also owns a single @FT_GlyphSlot object, as well  */
473   /*    as one or more @FT_Size objects.                                   */
474   /*                                                                       */
475   /*    Use @FT_New_Face or @FT_Open_Face to create a new face object from */
476   /*    a given filepathname or a custom input stream.                     */
477   /*                                                                       */
478   /*    Use @FT_Done_Face to destroy it (along with its slot and sizes).   */
479   /*                                                                       */
480   /* <Also>                                                                */
481   /*    See @FT_FaceRec for the publicly accessible fields of a given face */
482   /*    object.                                                            */
483   /*                                                                       */
484   typedef struct FT_FaceRec_*  FT_Face;
485
486
487   /*************************************************************************/
488   /*                                                                       */
489   /* <Type>                                                                */
490   /*    FT_Size                                                            */
491   /*                                                                       */
492   /* <Description>                                                         */
493   /*    A handle to an object used to model a face scaled to a given       */
494   /*    character size.                                                    */
495   /*                                                                       */
496   /* <Note>                                                                */
497   /*    Each @FT_Face has an _active_ @FT_Size object that is used by      */
498   /*    functions like @FT_Load_Glyph to determine the scaling             */
499   /*    transformation that in turn is used to load and hint glyphs and    */
500   /*    metrics.                                                           */
501   /*                                                                       */
502   /*    You can use @FT_Set_Char_Size, @FT_Set_Pixel_Sizes,                */
503   /*    @FT_Request_Size or even @FT_Select_Size to change the content     */
504   /*    (i.e., the scaling values) of the active @FT_Size.                 */
505   /*                                                                       */
506   /*    You can use @FT_New_Size to create additional size objects for a   */
507   /*    given @FT_Face, but they won't be used by other functions until    */
508   /*    you activate it through @FT_Activate_Size.  Only one size can be   */
509   /*    activated at any given time per face.                              */
510   /*                                                                       */
511   /* <Also>                                                                */
512   /*    See @FT_SizeRec for the publicly accessible fields of a given size */
513   /*    object.                                                            */
514   /*                                                                       */
515   typedef struct FT_SizeRec_*  FT_Size;
516
517
518   /*************************************************************************/
519   /*                                                                       */
520   /* <Type>                                                                */
521   /*    FT_GlyphSlot                                                       */
522   /*                                                                       */
523   /* <Description>                                                         */
524   /*    A handle to a given `glyph slot'.  A slot is a container where it  */
525   /*    is possible to load any of the glyphs contained in its parent      */
526   /*    face.                                                              */
527   /*                                                                       */
528   /*    In other words, each time you call @FT_Load_Glyph or               */
529   /*    @FT_Load_Char, the slot's content is erased by the new glyph data, */
530   /*    i.e., the glyph's metrics, its image (bitmap or outline), and      */
531   /*    other control information.                                         */
532   /*                                                                       */
533   /* <Also>                                                                */
534   /*    See @FT_GlyphSlotRec for the publicly accessible glyph fields.     */
535   /*                                                                       */
536   typedef struct FT_GlyphSlotRec_*  FT_GlyphSlot;
537
538
539   /*************************************************************************/
540   /*                                                                       */
541   /* <Type>                                                                */
542   /*    FT_CharMap                                                         */
543   /*                                                                       */
544   /* <Description>                                                         */
545   /*    A handle to a given character map.  A charmap is used to translate */
546   /*    character codes in a given encoding into glyph indexes for its     */
547   /*    parent's face.  Some font formats may provide several charmaps per */
548   /*    font.                                                              */
549   /*                                                                       */
550   /*    Each face object owns zero or more charmaps, but only one of them  */
551   /*    can be `active' and used by @FT_Get_Char_Index or @FT_Load_Char.   */
552   /*                                                                       */
553   /*    The list of available charmaps in a face is available through the  */
554   /*    `face->num_charmaps' and `face->charmaps' fields of @FT_FaceRec.   */
555   /*                                                                       */
556   /*    The currently active charmap is available as `face->charmap'.      */
557   /*    You should call @FT_Set_Charmap to change it.                      */
558   /*                                                                       */
559   /* <Note>                                                                */
560   /*    When a new face is created (either through @FT_New_Face or         */
561   /*    @FT_Open_Face), the library looks for a Unicode charmap within     */
562   /*    the list and automatically activates it.                           */
563   /*                                                                       */
564   /* <Also>                                                                */
565   /*    See @FT_CharMapRec for the publicly accessible fields of a given   */
566   /*    character map.                                                     */
567   /*                                                                       */
568   typedef struct FT_CharMapRec_*  FT_CharMap;
569
570
571   /*************************************************************************/
572   /*                                                                       */
573   /* <Macro>                                                               */
574   /*    FT_ENC_TAG                                                         */
575   /*                                                                       */
576   /* <Description>                                                         */
577   /*    This macro converts four-letter tags into an unsigned long.  It is */
578   /*    used to define `encoding' identifiers (see @FT_Encoding).          */
579   /*                                                                       */
580   /* <Note>                                                                */
581   /*    Since many 16-bit compilers don't like 32-bit enumerations, you    */
582   /*    should redefine this macro in case of problems to something like   */
583   /*    this:                                                              */
584   /*                                                                       */
585   /*    {                                                                  */
586   /*      #define FT_ENC_TAG( value, a, b, c, d )  value                   */
587   /*    }                                                                  */
588   /*                                                                       */
589   /*    to get a simple enumeration without assigning special numbers.     */
590   /*                                                                       */
591
592 #ifndef FT_ENC_TAG
593 #define FT_ENC_TAG( value, a, b, c, d )         \
594           value = ( ( (FT_UInt32)(a) << 24 ) |  \
595                     ( (FT_UInt32)(b) << 16 ) |  \
596                     ( (FT_UInt32)(c) <<  8 ) |  \
597                       (FT_UInt32)(d)         )
598
599 #endif /* FT_ENC_TAG */
600
601
602   /*************************************************************************/
603   /*                                                                       */
604   /* <Enum>                                                                */
605   /*    FT_Encoding                                                        */
606   /*                                                                       */
607   /* <Description>                                                         */
608   /*    An enumeration used to specify character sets supported by         */
609   /*    charmaps.  Used in the @FT_Select_Charmap API function.            */
610   /*                                                                       */
611   /* <Note>                                                                */
612   /*    Despite the name, this enumeration lists specific character        */
613   /*    repertories (i.e., charsets), and not text encoding methods (e.g., */
614   /*    UTF-8, UTF-16, etc.).                                              */
615   /*                                                                       */
616   /*    Other encodings might be defined in the future.                    */
617   /*                                                                       */
618   /* <Values>                                                              */
619   /*    FT_ENCODING_NONE ::                                                */
620   /*      The encoding value~0 is reserved.                                */
621   /*                                                                       */
622   /*    FT_ENCODING_UNICODE ::                                             */
623   /*      Corresponds to the Unicode character set.  This value covers     */
624   /*      all versions of the Unicode repertoire, including ASCII and      */
625   /*      Latin-1.  Most fonts include a Unicode charmap, but not all      */
626   /*      of them.                                                         */
627   /*                                                                       */
628   /*      For example, if you want to access Unicode value U+1F028 (and    */
629   /*      the font contains it), use value 0x1F028 as the input value for  */
630   /*      @FT_Get_Char_Index.                                              */
631   /*                                                                       */
632   /*    FT_ENCODING_MS_SYMBOL ::                                           */
633   /*      Corresponds to the Microsoft Symbol encoding, used to encode     */
634   /*      mathematical symbols in the 32..255 character code range.  For   */
635   /*      more information, see                                            */
636   /*      `http://www.kostis.net/charsets/symbol.htm'.                     */
637   /*                                                                       */
638   /*    FT_ENCODING_SJIS ::                                                */
639   /*      Corresponds to Japanese SJIS encoding.  More info at             */
640   /*      at `http://en.wikipedia.org/wiki/Shift_JIS'.                     */
641   /*      See note on multi-byte encodings below.                          */
642   /*                                                                       */
643   /*    FT_ENCODING_GB2312 ::                                              */
644   /*      Corresponds to an encoding system for Simplified Chinese as used */
645   /*      used in mainland China.                                          */
646   /*                                                                       */
647   /*    FT_ENCODING_BIG5 ::                                                */
648   /*      Corresponds to an encoding system for Traditional Chinese as     */
649   /*      used in Taiwan and Hong Kong.                                    */
650   /*                                                                       */
651   /*    FT_ENCODING_WANSUNG ::                                             */
652   /*      Corresponds to the Korean encoding system known as Wansung.      */
653   /*      For more information see                                         */
654   /*      `http://msdn.microsoft.com/en-US/goglobal/cc305154'.             */
655   /*                                                                       */
656   /*    FT_ENCODING_JOHAB ::                                               */
657   /*      The Korean standard character set (KS~C 5601-1992), which        */
658   /*      corresponds to MS Windows code page 1361.  This character set    */
659   /*      includes all possible Hangeul character combinations.            */
660   /*                                                                       */
661   /*    FT_ENCODING_ADOBE_LATIN_1 ::                                       */
662   /*      Corresponds to a Latin-1 encoding as defined in a Type~1         */
663   /*      PostScript font.  It is limited to 256 character codes.          */
664   /*                                                                       */
665   /*    FT_ENCODING_ADOBE_STANDARD ::                                      */
666   /*      Corresponds to the Adobe Standard encoding, as found in Type~1,  */
667   /*      CFF, and OpenType/CFF fonts.  It is limited to 256 character     */
668   /*      codes.                                                           */
669   /*                                                                       */
670   /*    FT_ENCODING_ADOBE_EXPERT ::                                        */
671   /*      Corresponds to the Adobe Expert encoding, as found in Type~1,    */
672   /*      CFF, and OpenType/CFF fonts.  It is limited to 256 character     */
673   /*      codes.                                                           */
674   /*                                                                       */
675   /*    FT_ENCODING_ADOBE_CUSTOM ::                                        */
676   /*      Corresponds to a custom encoding, as found in Type~1, CFF, and   */
677   /*      OpenType/CFF fonts.  It is limited to 256 character codes.       */
678   /*                                                                       */
679   /*    FT_ENCODING_APPLE_ROMAN ::                                         */
680   /*      Corresponds to the 8-bit Apple roman encoding.  Many TrueType    */
681   /*      and OpenType fonts contain a charmap for this encoding, since    */
682   /*      older versions of Mac OS are able to use it.                     */
683   /*                                                                       */
684   /*    FT_ENCODING_OLD_LATIN_2 ::                                         */
685   /*      This value is deprecated and was never used nor reported by      */
686   /*      FreeType.  Don't use or test for it.                             */
687   /*                                                                       */
688   /*    FT_ENCODING_MS_SJIS ::                                             */
689   /*      Same as FT_ENCODING_SJIS.  Deprecated.                           */
690   /*                                                                       */
691   /*    FT_ENCODING_MS_GB2312 ::                                           */
692   /*      Same as FT_ENCODING_GB2312.  Deprecated.                         */
693   /*                                                                       */
694   /*    FT_ENCODING_MS_BIG5 ::                                             */
695   /*      Same as FT_ENCODING_BIG5.  Deprecated.                           */
696   /*                                                                       */
697   /*    FT_ENCODING_MS_WANSUNG ::                                          */
698   /*      Same as FT_ENCODING_WANSUNG.  Deprecated.                        */
699   /*                                                                       */
700   /*    FT_ENCODING_MS_JOHAB ::                                            */
701   /*      Same as FT_ENCODING_JOHAB.  Deprecated.                          */
702   /*                                                                       */
703   /* <Note>                                                                */
704   /*    By default, FreeType automatically synthesizes a Unicode charmap   */
705   /*    for PostScript fonts, using their glyph names dictionaries.        */
706   /*    However, it also reports the encodings defined explicitly in the   */
707   /*    font file, for the cases when they are needed, with the Adobe      */
708   /*    values as well.                                                    */
709   /*                                                                       */
710   /*    FT_ENCODING_NONE is set by the BDF and PCF drivers if the charmap  */
711   /*    is neither Unicode nor ISO-8859-1 (otherwise it is set to          */
712   /*    FT_ENCODING_UNICODE).  Use @FT_Get_BDF_Charset_ID to find out      */
713   /*    which encoding is really present.  If, for example, the            */
714   /*    `cs_registry' field is `KOI8' and the `cs_encoding' field is `R',  */
715   /*    the font is encoded in KOI8-R.                                     */
716   /*                                                                       */
717   /*    FT_ENCODING_NONE is always set (with a single exception) by the    */
718   /*    winfonts driver.  Use @FT_Get_WinFNT_Header and examine the        */
719   /*    `charset' field of the @FT_WinFNT_HeaderRec structure to find out  */
720   /*    which encoding is really present.  For example,                    */
721   /*    @FT_WinFNT_ID_CP1251 (204) means Windows code page 1251 (for       */
722   /*    Russian).                                                          */
723   /*                                                                       */
724   /*    FT_ENCODING_NONE is set if `platform_id' is @TT_PLATFORM_MACINTOSH */
725   /*    and `encoding_id' is not @TT_MAC_ID_ROMAN (otherwise it is set to  */
726   /*    FT_ENCODING_APPLE_ROMAN).                                          */
727   /*                                                                       */
728   /*    If `platform_id' is @TT_PLATFORM_MACINTOSH, use the function       */
729   /*    @FT_Get_CMap_Language_ID to query the Mac language ID that may     */
730   /*    be needed to be able to distinguish Apple encoding variants.  See  */
731   /*                                                                       */
732   /*      http://www.unicode.org/Public/MAPPINGS/VENDORS/APPLE/Readme.txt  */
733   /*                                                                       */
734   /*    to get an idea how to do that.  Basically, if the language ID      */
735   /*    is~0, don't use it, otherwise subtract 1 from the language ID.     */
736   /*    Then examine `encoding_id'.  If, for example, `encoding_id' is     */
737   /*    @TT_MAC_ID_ROMAN and the language ID (minus~1) is                  */
738   /*    `TT_MAC_LANGID_GREEK', it is the Greek encoding, not Roman.        */
739   /*    @TT_MAC_ID_ARABIC with `TT_MAC_LANGID_FARSI' means the Farsi       */
740   /*    variant the Arabic encoding.                                       */
741   /*                                                                       */
742   typedef enum  FT_Encoding_
743   {
744     FT_ENC_TAG( FT_ENCODING_NONE, 0, 0, 0, 0 ),
745
746     FT_ENC_TAG( FT_ENCODING_MS_SYMBOL, 's', 'y', 'm', 'b' ),
747     FT_ENC_TAG( FT_ENCODING_UNICODE,   'u', 'n', 'i', 'c' ),
748
749     FT_ENC_TAG( FT_ENCODING_SJIS,    's', 'j', 'i', 's' ),
750     FT_ENC_TAG( FT_ENCODING_GB2312,  'g', 'b', ' ', ' ' ),
751     FT_ENC_TAG( FT_ENCODING_BIG5,    'b', 'i', 'g', '5' ),
752     FT_ENC_TAG( FT_ENCODING_WANSUNG, 'w', 'a', 'n', 's' ),
753     FT_ENC_TAG( FT_ENCODING_JOHAB,   'j', 'o', 'h', 'a' ),
754
755     /* for backwards compatibility */
756     FT_ENCODING_MS_SJIS    = FT_ENCODING_SJIS,
757     FT_ENCODING_MS_GB2312  = FT_ENCODING_GB2312,
758     FT_ENCODING_MS_BIG5    = FT_ENCODING_BIG5,
759     FT_ENCODING_MS_WANSUNG = FT_ENCODING_WANSUNG,
760     FT_ENCODING_MS_JOHAB   = FT_ENCODING_JOHAB,
761
762     FT_ENC_TAG( FT_ENCODING_ADOBE_STANDARD, 'A', 'D', 'O', 'B' ),
763     FT_ENC_TAG( FT_ENCODING_ADOBE_EXPERT,   'A', 'D', 'B', 'E' ),
764     FT_ENC_TAG( FT_ENCODING_ADOBE_CUSTOM,   'A', 'D', 'B', 'C' ),
765     FT_ENC_TAG( FT_ENCODING_ADOBE_LATIN_1,  'l', 'a', 't', '1' ),
766
767     FT_ENC_TAG( FT_ENCODING_OLD_LATIN_2, 'l', 'a', 't', '2' ),
768
769     FT_ENC_TAG( FT_ENCODING_APPLE_ROMAN, 'a', 'r', 'm', 'n' )
770
771   } FT_Encoding;
772
773
774   /* these constants are deprecated; use the corresponding `FT_Encoding' */
775   /* values instead                                                      */
776 #define ft_encoding_none            FT_ENCODING_NONE
777 #define ft_encoding_unicode         FT_ENCODING_UNICODE
778 #define ft_encoding_symbol          FT_ENCODING_MS_SYMBOL
779 #define ft_encoding_latin_1         FT_ENCODING_ADOBE_LATIN_1
780 #define ft_encoding_latin_2         FT_ENCODING_OLD_LATIN_2
781 #define ft_encoding_sjis            FT_ENCODING_SJIS
782 #define ft_encoding_gb2312          FT_ENCODING_GB2312
783 #define ft_encoding_big5            FT_ENCODING_BIG5
784 #define ft_encoding_wansung         FT_ENCODING_WANSUNG
785 #define ft_encoding_johab           FT_ENCODING_JOHAB
786
787 #define ft_encoding_adobe_standard  FT_ENCODING_ADOBE_STANDARD
788 #define ft_encoding_adobe_expert    FT_ENCODING_ADOBE_EXPERT
789 #define ft_encoding_adobe_custom    FT_ENCODING_ADOBE_CUSTOM
790 #define ft_encoding_apple_roman     FT_ENCODING_APPLE_ROMAN
791
792
793   /*************************************************************************/
794   /*                                                                       */
795   /* <Struct>                                                              */
796   /*    FT_CharMapRec                                                      */
797   /*                                                                       */
798   /* <Description>                                                         */
799   /*    The base charmap structure.                                        */
800   /*                                                                       */
801   /* <Fields>                                                              */
802   /*    face        :: A handle to the parent face object.                 */
803   /*                                                                       */
804   /*    encoding    :: An @FT_Encoding tag identifying the charmap.  Use   */
805   /*                   this with @FT_Select_Charmap.                       */
806   /*                                                                       */
807   /*    platform_id :: An ID number describing the platform for the        */
808   /*                   following encoding ID.  This comes directly from    */
809   /*                   the TrueType specification and should be emulated   */
810   /*                   for other formats.                                  */
811   /*                                                                       */
812   /*    encoding_id :: A platform specific encoding number.  This also     */
813   /*                   comes from the TrueType specification and should be */
814   /*                   emulated similarly.                                 */
815   /*                                                                       */
816   typedef struct  FT_CharMapRec_
817   {
818     FT_Face      face;
819     FT_Encoding  encoding;
820     FT_UShort    platform_id;
821     FT_UShort    encoding_id;
822
823   } FT_CharMapRec;
824
825
826   /*************************************************************************/
827   /*************************************************************************/
828   /*                                                                       */
829   /*                 B A S E   O B J E C T   C L A S S E S                 */
830   /*                                                                       */
831   /*************************************************************************/
832   /*************************************************************************/
833
834
835   /*************************************************************************/
836   /*                                                                       */
837   /* <Type>                                                                */
838   /*    FT_Face_Internal                                                   */
839   /*                                                                       */
840   /* <Description>                                                         */
841   /*    An opaque handle to an `FT_Face_InternalRec' structure, used to    */
842   /*    model private data of a given @FT_Face object.                     */
843   /*                                                                       */
844   /*    This structure might change between releases of FreeType~2 and is  */
845   /*    not generally available to client applications.                    */
846   /*                                                                       */
847   typedef struct FT_Face_InternalRec_*  FT_Face_Internal;
848
849
850   /*************************************************************************/
851   /*                                                                       */
852   /* <Struct>                                                              */
853   /*    FT_FaceRec                                                         */
854   /*                                                                       */
855   /* <Description>                                                         */
856   /*    FreeType root face class structure.  A face object models a        */
857   /*    typeface in a font file.                                           */
858   /*                                                                       */
859   /* <Fields>                                                              */
860   /*    num_faces           :: The number of faces in the font file.  Some */
861   /*                           font formats can have multiple faces in     */
862   /*                           a font file.                                */
863   /*                                                                       */
864   /*    face_index          :: The index of the face in the font file.  It */
865   /*                           is set to~0 if there is only one face in    */
866   /*                           the font file.                              */
867   /*                                                                       */
868   /*    face_flags          :: A set of bit flags that give important      */
869   /*                           information about the face; see             */
870   /*                           @FT_FACE_FLAG_XXX for the details.          */
871   /*                                                                       */
872   /*    style_flags         :: A set of bit flags indicating the style of  */
873   /*                           the face; see @FT_STYLE_FLAG_XXX for the    */
874   /*                           details.                                    */
875   /*                                                                       */
876   /*    num_glyphs          :: The number of glyphs in the face.  If the   */
877   /*                           face is scalable and has sbits (see         */
878   /*                           `num_fixed_sizes'), it is set to the number */
879   /*                           of outline glyphs.                          */
880   /*                                                                       */
881   /*                           For CID-keyed fonts, this value gives the   */
882   /*                           highest CID used in the font.               */
883   /*                                                                       */
884   /*    family_name         :: The face's family name.  This is an ASCII   */
885   /*                           string, usually in English, that describes  */
886   /*                           the typeface's family (like `Times New      */
887   /*                           Roman', `Bodoni', `Garamond', etc).  This   */
888   /*                           is a least common denominator used to list  */
889   /*                           fonts.  Some formats (TrueType & OpenType)  */
890   /*                           provide localized and Unicode versions of   */
891   /*                           this string.  Applications should use the   */
892   /*                           format specific interface to access them.   */
893   /*                           Can be NULL (e.g., in fonts embedded in a   */
894   /*                           PDF file).                                  */
895   /*                                                                       */
896   /*    style_name          :: The face's style name.  This is an ASCII    */
897   /*                           string, usually in English, that describes  */
898   /*                           the typeface's style (like `Italic',        */
899   /*                           `Bold', `Condensed', etc).  Not all font    */
900   /*                           formats provide a style name, so this field */
901   /*                           is optional, and can be set to NULL.  As    */
902   /*                           for `family_name', some formats provide     */
903   /*                           localized and Unicode versions of this      */
904   /*                           string.  Applications should use the format */
905   /*                           specific interface to access them.          */
906   /*                                                                       */
907   /*    num_fixed_sizes     :: The number of bitmap strikes in the face.   */
908   /*                           Even if the face is scalable, there might   */
909   /*                           still be bitmap strikes, which are called   */
910   /*                           `sbits' in that case.                       */
911   /*                                                                       */
912   /*    available_sizes     :: An array of @FT_Bitmap_Size for all bitmap  */
913   /*                           strikes in the face.  It is set to NULL if  */
914   /*                           there is no bitmap strike.                  */
915   /*                                                                       */
916   /*    num_charmaps        :: The number of charmaps in the face.         */
917   /*                                                                       */
918   /*    charmaps            :: An array of the charmaps of the face.       */
919   /*                                                                       */
920   /*    generic             :: A field reserved for client uses.  See the  */
921   /*                           @FT_Generic type description.               */
922   /*                                                                       */
923   /*    bbox                :: The font bounding box.  Coordinates are     */
924   /*                           expressed in font units (see                */
925   /*                           `units_per_EM').  The box is large enough   */
926   /*                           to contain any glyph from the font.  Thus,  */
927   /*                           `bbox.yMax' can be seen as the `maximum     */
928   /*                           ascender', and `bbox.yMin' as the `minimum  */
929   /*                           descender'.  Only relevant for scalable     */
930   /*                           formats.                                    */
931   /*                                                                       */
932   /*                           Note that the bounding box might be off by  */
933   /*                           (at least) one pixel for hinted fonts.  See */
934   /*                           @FT_Size_Metrics for further discussion.    */
935   /*                                                                       */
936   /*    units_per_EM        :: The number of font units per EM square for  */
937   /*                           this face.  This is typically 2048 for      */
938   /*                           TrueType fonts, and 1000 for Type~1 fonts.  */
939   /*                           Only relevant for scalable formats.         */
940   /*                                                                       */
941   /*    ascender            :: The typographic ascender of the face,       */
942   /*                           expressed in font units.  For font formats  */
943   /*                           not having this information, it is set to   */
944   /*                           `bbox.yMax'.  Only relevant for scalable    */
945   /*                           formats.                                    */
946   /*                                                                       */
947   /*    descender           :: The typographic descender of the face,      */
948   /*                           expressed in font units.  For font formats  */
949   /*                           not having this information, it is set to   */
950   /*                           `bbox.yMin'.  Note that this field is       */
951   /*                           usually negative.  Only relevant for        */
952   /*                           scalable formats.                           */
953   /*                                                                       */
954   /*    height              :: This value is the vertical distance         */
955   /*                           between two consecutive baselines,          */
956   /*                           expressed in font units.  It is always      */
957   /*                           positive.  Only relevant for scalable       */
958   /*                           formats.                                    */
959   /*                                                                       */
960   /*                           If you want the global glyph height, use    */
961   /*                           `ascender - descender'.                     */
962   /*                                                                       */
963   /*    max_advance_width   :: The maximum advance width, in font units,   */
964   /*                           for all glyphs in this face.  This can be   */
965   /*                           used to make word wrapping computations     */
966   /*                           faster.  Only relevant for scalable         */
967   /*                           formats.                                    */
968   /*                                                                       */
969   /*    max_advance_height  :: The maximum advance height, in font units,  */
970   /*                           for all glyphs in this face.  This is only  */
971   /*                           relevant for vertical layouts, and is set   */
972   /*                           to `height' for fonts that do not provide   */
973   /*                           vertical metrics.  Only relevant for        */
974   /*                           scalable formats.                           */
975   /*                                                                       */
976   /*    underline_position  :: The position, in font units, of the         */
977   /*                           underline line for this face.  It is the    */
978   /*                           center of the underlining stem.  Only       */
979   /*                           relevant for scalable formats.              */
980   /*                                                                       */
981   /*    underline_thickness :: The thickness, in font units, of the        */
982   /*                           underline for this face.  Only relevant for */
983   /*                           scalable formats.                           */
984   /*                                                                       */
985   /*    glyph               :: The face's associated glyph slot(s).        */
986   /*                                                                       */
987   /*    size                :: The current active size for this face.      */
988   /*                                                                       */
989   /*    charmap             :: The current active charmap for this face.   */
990   /*                                                                       */
991   /* <Note>                                                                */
992   /*    Fields may be changed after a call to @FT_Attach_File or           */
993   /*    @FT_Attach_Stream.                                                 */
994   /*                                                                       */
995   typedef struct  FT_FaceRec_
996   {
997     FT_Long           num_faces;
998     FT_Long           face_index;
999
1000     FT_Long           face_flags;
1001     FT_Long           style_flags;
1002
1003     FT_Long           num_glyphs;
1004
1005     FT_String*        family_name;
1006     FT_String*        style_name;
1007
1008     FT_Int            num_fixed_sizes;
1009     FT_Bitmap_Size*   available_sizes;
1010
1011     FT_Int            num_charmaps;
1012     FT_CharMap*       charmaps;
1013
1014     FT_Generic        generic;
1015
1016     /*# The following member variables (down to `underline_thickness') */
1017     /*# are only relevant to scalable outlines; cf. @FT_Bitmap_Size    */
1018     /*# for bitmap fonts.                                              */
1019     FT_BBox           bbox;
1020
1021     FT_UShort         units_per_EM;
1022     FT_Short          ascender;
1023     FT_Short          descender;
1024     FT_Short          height;
1025
1026     FT_Short          max_advance_width;
1027     FT_Short          max_advance_height;
1028
1029     FT_Short          underline_position;
1030     FT_Short          underline_thickness;
1031
1032     FT_GlyphSlot      glyph;
1033     FT_Size           size;
1034     FT_CharMap        charmap;
1035
1036     /*@private begin */
1037
1038     FT_Driver         driver;
1039     FT_Memory         memory;
1040     FT_Stream         stream;
1041
1042     FT_ListRec        sizes_list;
1043
1044     FT_Generic        autohint;   /* face-specific auto-hinter data */
1045     void*             extensions; /* unused                         */
1046
1047     FT_Face_Internal  internal;
1048
1049     /*@private end */
1050
1051   } FT_FaceRec;
1052
1053
1054   /*************************************************************************/
1055   /*                                                                       */
1056   /* <Enum>                                                                */
1057   /*    FT_FACE_FLAG_XXX                                                   */
1058   /*                                                                       */
1059   /* <Description>                                                         */
1060   /*    A list of bit flags used in the `face_flags' field of the          */
1061   /*    @FT_FaceRec structure.  They inform client applications of         */
1062   /*    properties of the corresponding face.                              */
1063   /*                                                                       */
1064   /* <Values>                                                              */
1065   /*    FT_FACE_FLAG_SCALABLE ::                                           */
1066   /*      Indicates that the face contains outline glyphs.  This doesn't   */
1067   /*      prevent bitmap strikes, i.e., a face can have both this and      */
1068   /*      and @FT_FACE_FLAG_FIXED_SIZES set.                               */
1069   /*                                                                       */
1070   /*    FT_FACE_FLAG_FIXED_SIZES ::                                        */
1071   /*      Indicates that the face contains bitmap strikes.  See also the   */
1072   /*      `num_fixed_sizes' and `available_sizes' fields of @FT_FaceRec.   */
1073   /*                                                                       */
1074   /*    FT_FACE_FLAG_FIXED_WIDTH ::                                        */
1075   /*      Indicates that the face contains fixed-width characters (like    */
1076   /*      Courier, Lucido, MonoType, etc.).                                */
1077   /*                                                                       */
1078   /*    FT_FACE_FLAG_SFNT ::                                               */
1079   /*      Indicates that the face uses the `sfnt' storage scheme.  For     */
1080   /*      now, this means TrueType and OpenType.                           */
1081   /*                                                                       */
1082   /*    FT_FACE_FLAG_HORIZONTAL ::                                         */
1083   /*      Indicates that the face contains horizontal glyph metrics.  This */
1084   /*      should be set for all common formats.                            */
1085   /*                                                                       */
1086   /*    FT_FACE_FLAG_VERTICAL ::                                           */
1087   /*      Indicates that the face contains vertical glyph metrics.  This   */
1088   /*      is only available in some formats, not all of them.              */
1089   /*                                                                       */
1090   /*    FT_FACE_FLAG_KERNING ::                                            */
1091   /*      Indicates that the face contains kerning information.  If set,   */
1092   /*      the kerning distance can be retrieved through the function       */
1093   /*      @FT_Get_Kerning.  Otherwise the function always return the       */
1094   /*      vector (0,0).  Note that FreeType doesn't handle kerning data    */
1095   /*      from the `GPOS' table (as present in some OpenType fonts).       */
1096   /*                                                                       */
1097   /*    FT_FACE_FLAG_FAST_GLYPHS ::                                        */
1098   /*      THIS FLAG IS DEPRECATED.  DO NOT USE OR TEST IT.                 */
1099   /*                                                                       */
1100   /*    FT_FACE_FLAG_MULTIPLE_MASTERS ::                                   */
1101   /*      Indicates that the font contains multiple masters and is capable */
1102   /*      of interpolating between them.  See the multiple-masters         */
1103   /*      specific API for details.                                        */
1104   /*                                                                       */
1105   /*    FT_FACE_FLAG_GLYPH_NAMES ::                                        */
1106   /*      Indicates that the font contains glyph names that can be         */
1107   /*      retrieved through @FT_Get_Glyph_Name.  Note that some TrueType   */
1108   /*      fonts contain broken glyph name tables.  Use the function        */
1109   /*      @FT_Has_PS_Glyph_Names when needed.                              */
1110   /*                                                                       */
1111   /*    FT_FACE_FLAG_EXTERNAL_STREAM ::                                    */
1112   /*      Used internally by FreeType to indicate that a face's stream was */
1113   /*      provided by the client application and should not be destroyed   */
1114   /*      when @FT_Done_Face is called.  Don't read or test this flag.     */
1115   /*                                                                       */
1116   /*    FT_FACE_FLAG_HINTER ::                                             */
1117   /*      Set if the font driver has a hinting machine of its own.  For    */
1118   /*      example, with TrueType fonts, it makes sense to use data from    */
1119   /*      the SFNT `gasp' table only if the native TrueType hinting engine */
1120   /*      (with the bytecode interpreter) is available and active.         */
1121   /*                                                                       */
1122   /*    FT_FACE_FLAG_CID_KEYED ::                                          */
1123   /*      Set if the font is CID-keyed.  In that case, the font is not     */
1124   /*      accessed by glyph indices but by CID values.  For subsetted      */
1125   /*      CID-keyed fonts this has the consequence that not all index      */
1126   /*      values are a valid argument to FT_Load_Glyph.  Only the CID      */
1127   /*      values for which corresponding glyphs in the subsetted font      */
1128   /*      exist make FT_Load_Glyph return successfully; in all other cases */
1129   /*      you get an `FT_Err_Invalid_Argument' error.                      */
1130   /*                                                                       */
1131   /*      Note that CID-keyed fonts that are in an SFNT wrapper don't      */
1132   /*      have this flag set since the glyphs are accessed in the normal   */
1133   /*      way (using contiguous indices); the `CID-ness' isn't visible to  */
1134   /*      the application.                                                 */
1135   /*                                                                       */
1136   /*    FT_FACE_FLAG_TRICKY ::                                             */
1137   /*      Set if the font is `tricky', this is, it always needs the        */
1138   /*      font format's native hinting engine to get a reasonable result.  */
1139   /*      A typical example is the Chinese font `mingli.ttf' that uses     */
1140   /*      TrueType bytecode instructions to move and scale all of its      */
1141   /*      subglyphs.                                                       */
1142   /*                                                                       */
1143   /*      It is not possible to autohint such fonts using                  */
1144   /*      @FT_LOAD_FORCE_AUTOHINT; it will also ignore                     */
1145   /*      @FT_LOAD_NO_HINTING.  You have to set both @FT_LOAD_NO_HINTING   */
1146   /*      and @FT_LOAD_NO_AUTOHINT to really disable hinting; however, you */
1147   /*      probably never want this except for demonstration purposes.      */
1148   /*                                                                       */
1149   /*      Currently, there are about a dozen TrueType fonts in the list of */
1150   /*      tricky fonts; they are hard-coded in file `ttobjs.c'.            */
1151   /*                                                                       */
1152   /*    FT_FACE_FLAG_COLOR ::                                              */
1153   /*      Set if the font has color glyph tables.  To access color glyphs  */
1154   /*      use @FT_LOAD_COLOR.                                              */
1155   /*                                                                       */
1156 #define FT_FACE_FLAG_SCALABLE          ( 1L <<  0 )
1157 #define FT_FACE_FLAG_FIXED_SIZES       ( 1L <<  1 )
1158 #define FT_FACE_FLAG_FIXED_WIDTH       ( 1L <<  2 )
1159 #define FT_FACE_FLAG_SFNT              ( 1L <<  3 )
1160 #define FT_FACE_FLAG_HORIZONTAL        ( 1L <<  4 )
1161 #define FT_FACE_FLAG_VERTICAL          ( 1L <<  5 )
1162 #define FT_FACE_FLAG_KERNING           ( 1L <<  6 )
1163 #define FT_FACE_FLAG_FAST_GLYPHS       ( 1L <<  7 )
1164 #define FT_FACE_FLAG_MULTIPLE_MASTERS  ( 1L <<  8 )
1165 #define FT_FACE_FLAG_GLYPH_NAMES       ( 1L <<  9 )
1166 #define FT_FACE_FLAG_EXTERNAL_STREAM   ( 1L << 10 )
1167 #define FT_FACE_FLAG_HINTER            ( 1L << 11 )
1168 #define FT_FACE_FLAG_CID_KEYED         ( 1L << 12 )
1169 #define FT_FACE_FLAG_TRICKY            ( 1L << 13 )
1170 #define FT_FACE_FLAG_COLOR             ( 1L << 14 )
1171
1172
1173   /*************************************************************************
1174    *
1175    * @macro:
1176    *   FT_HAS_HORIZONTAL( face )
1177    *
1178    * @description:
1179    *   A macro that returns true whenever a face object contains
1180    *   horizontal metrics (this is true for all font formats though).
1181    *
1182    * @also:
1183    *   @FT_HAS_VERTICAL can be used to check for vertical metrics.
1184    *
1185    */
1186 #define FT_HAS_HORIZONTAL( face ) \
1187           ( face->face_flags & FT_FACE_FLAG_HORIZONTAL )
1188
1189
1190   /*************************************************************************
1191    *
1192    * @macro:
1193    *   FT_HAS_VERTICAL( face )
1194    *
1195    * @description:
1196    *   A macro that returns true whenever a face object contains real
1197    *   vertical metrics (and not only synthesized ones).
1198    *
1199    */
1200 #define FT_HAS_VERTICAL( face ) \
1201           ( face->face_flags & FT_FACE_FLAG_VERTICAL )
1202
1203
1204   /*************************************************************************
1205    *
1206    * @macro:
1207    *   FT_HAS_KERNING( face )
1208    *
1209    * @description:
1210    *   A macro that returns true whenever a face object contains kerning
1211    *   data that can be accessed with @FT_Get_Kerning.
1212    *
1213    */
1214 #define FT_HAS_KERNING( face ) \
1215           ( face->face_flags & FT_FACE_FLAG_KERNING )
1216
1217
1218   /*************************************************************************
1219    *
1220    * @macro:
1221    *   FT_IS_SCALABLE( face )
1222    *
1223    * @description:
1224    *   A macro that returns true whenever a face object contains a scalable
1225    *   font face (true for TrueType, Type~1, Type~42, CID, OpenType/CFF,
1226    *   and PFR font formats.
1227    *
1228    */
1229 #define FT_IS_SCALABLE( face ) \
1230           ( face->face_flags & FT_FACE_FLAG_SCALABLE )
1231
1232
1233   /*************************************************************************
1234    *
1235    * @macro:
1236    *   FT_IS_SFNT( face )
1237    *
1238    * @description:
1239    *   A macro that returns true whenever a face object contains a font
1240    *   whose format is based on the SFNT storage scheme.  This usually
1241    *   means: TrueType fonts, OpenType fonts, as well as SFNT-based embedded
1242    *   bitmap fonts.
1243    *
1244    *   If this macro is true, all functions defined in @FT_SFNT_NAMES_H and
1245    *   @FT_TRUETYPE_TABLES_H are available.
1246    *
1247    */
1248 #define FT_IS_SFNT( face ) \
1249           ( face->face_flags & FT_FACE_FLAG_SFNT )
1250
1251
1252   /*************************************************************************
1253    *
1254    * @macro:
1255    *   FT_IS_FIXED_WIDTH( face )
1256    *
1257    * @description:
1258    *   A macro that returns true whenever a face object contains a font face
1259    *   that contains fixed-width (or `monospace', `fixed-pitch', etc.)
1260    *   glyphs.
1261    *
1262    */
1263 #define FT_IS_FIXED_WIDTH( face ) \
1264           ( face->face_flags & FT_FACE_FLAG_FIXED_WIDTH )
1265
1266
1267   /*************************************************************************
1268    *
1269    * @macro:
1270    *   FT_HAS_FIXED_SIZES( face )
1271    *
1272    * @description:
1273    *   A macro that returns true whenever a face object contains some
1274    *   embedded bitmaps.  See the `available_sizes' field of the
1275    *   @FT_FaceRec structure.
1276    *
1277    */
1278 #define FT_HAS_FIXED_SIZES( face ) \
1279           ( face->face_flags & FT_FACE_FLAG_FIXED_SIZES )
1280
1281
1282   /*************************************************************************
1283    *
1284    * @macro:
1285    *   FT_HAS_FAST_GLYPHS( face )
1286    *
1287    * @description:
1288    *   Deprecated.
1289    *
1290    */
1291 #define FT_HAS_FAST_GLYPHS( face )  0
1292
1293
1294   /*************************************************************************
1295    *
1296    * @macro:
1297    *   FT_HAS_GLYPH_NAMES( face )
1298    *
1299    * @description:
1300    *   A macro that returns true whenever a face object contains some glyph
1301    *   names that can be accessed through @FT_Get_Glyph_Name.
1302    *
1303    */
1304 #define FT_HAS_GLYPH_NAMES( face ) \
1305           ( face->face_flags & FT_FACE_FLAG_GLYPH_NAMES )
1306
1307
1308   /*************************************************************************
1309    *
1310    * @macro:
1311    *   FT_HAS_MULTIPLE_MASTERS( face )
1312    *
1313    * @description:
1314    *   A macro that returns true whenever a face object contains some
1315    *   multiple masters.  The functions provided by @FT_MULTIPLE_MASTERS_H
1316    *   are then available to choose the exact design you want.
1317    *
1318    */
1319 #define FT_HAS_MULTIPLE_MASTERS( face ) \
1320           ( face->face_flags & FT_FACE_FLAG_MULTIPLE_MASTERS )
1321
1322
1323   /*************************************************************************
1324    *
1325    * @macro:
1326    *   FT_IS_CID_KEYED( face )
1327    *
1328    * @description:
1329    *   A macro that returns true whenever a face object contains a CID-keyed
1330    *   font.  See the discussion of @FT_FACE_FLAG_CID_KEYED for more
1331    *   details.
1332    *
1333    *   If this macro is true, all functions defined in @FT_CID_H are
1334    *   available.
1335    *
1336    */
1337 #define FT_IS_CID_KEYED( face ) \
1338           ( face->face_flags & FT_FACE_FLAG_CID_KEYED )
1339
1340
1341   /*************************************************************************
1342    *
1343    * @macro:
1344    *   FT_IS_TRICKY( face )
1345    *
1346    * @description:
1347    *   A macro that returns true whenever a face represents a `tricky' font.
1348    *   See the discussion of @FT_FACE_FLAG_TRICKY for more details.
1349    *
1350    */
1351 #define FT_IS_TRICKY( face ) \
1352           ( face->face_flags & FT_FACE_FLAG_TRICKY )
1353
1354
1355   /*************************************************************************
1356    *
1357    * @macro:
1358    *   FT_HAS_COLOR( face )
1359    *
1360    * @description:
1361    *   A macro that returns true whenever a face object contains
1362    *   tables for color glyphs.
1363    *
1364    */
1365 #define FT_HAS_COLOR( face ) \
1366           ( face->face_flags & FT_FACE_FLAG_COLOR )
1367
1368
1369   /*************************************************************************/
1370   /*                                                                       */
1371   /* <Const>                                                               */
1372   /*    FT_STYLE_FLAG_XXX                                                  */
1373   /*                                                                       */
1374   /* <Description>                                                         */
1375   /*    A list of bit-flags used to indicate the style of a given face.    */
1376   /*    These are used in the `style_flags' field of @FT_FaceRec.          */
1377   /*                                                                       */
1378   /* <Values>                                                              */
1379   /*    FT_STYLE_FLAG_ITALIC ::                                            */
1380   /*      Indicates that a given face style is italic or oblique.          */
1381   /*                                                                       */
1382   /*    FT_STYLE_FLAG_BOLD ::                                              */
1383   /*      Indicates that a given face is bold.                             */
1384   /*                                                                       */
1385   /* <Note>                                                                */
1386   /*    The style information as provided by FreeType is very basic.  More */
1387   /*    details are beyond the scope and should be done on a higher level  */
1388   /*    (for example, by analyzing various fields of the `OS/2' table in   */
1389   /*    SFNT based fonts).                                                 */
1390   /*                                                                       */
1391 #define FT_STYLE_FLAG_ITALIC  ( 1 << 0 )
1392 #define FT_STYLE_FLAG_BOLD    ( 1 << 1 )
1393
1394
1395   /*************************************************************************/
1396   /*                                                                       */
1397   /* <Type>                                                                */
1398   /*    FT_Size_Internal                                                   */
1399   /*                                                                       */
1400   /* <Description>                                                         */
1401   /*    An opaque handle to an `FT_Size_InternalRec' structure, used to    */
1402   /*    model private data of a given @FT_Size object.                     */
1403   /*                                                                       */
1404   typedef struct FT_Size_InternalRec_*  FT_Size_Internal;
1405
1406
1407   /*************************************************************************/
1408   /*                                                                       */
1409   /* <Struct>                                                              */
1410   /*    FT_Size_Metrics                                                    */
1411   /*                                                                       */
1412   /* <Description>                                                         */
1413   /*    The size metrics structure gives the metrics of a size object.     */
1414   /*                                                                       */
1415   /* <Fields>                                                              */
1416   /*    x_ppem       :: The width of the scaled EM square in pixels, hence */
1417   /*                    the term `ppem' (pixels per EM).  It is also       */
1418   /*                    referred to as `nominal width'.                    */
1419   /*                                                                       */
1420   /*    y_ppem       :: The height of the scaled EM square in pixels,      */
1421   /*                    hence the term `ppem' (pixels per EM).  It is also */
1422   /*                    referred to as `nominal height'.                   */
1423   /*                                                                       */
1424   /*    x_scale      :: A 16.16 fractional scaling value used to convert   */
1425   /*                    horizontal metrics from font units to 26.6         */
1426   /*                    fractional pixels.  Only relevant for scalable     */
1427   /*                    font formats.                                      */
1428   /*                                                                       */
1429   /*    y_scale      :: A 16.16 fractional scaling value used to convert   */
1430   /*                    vertical metrics from font units to 26.6           */
1431   /*                    fractional pixels.  Only relevant for scalable     */
1432   /*                    font formats.                                      */
1433   /*                                                                       */
1434   /*    ascender     :: The ascender in 26.6 fractional pixels.  See       */
1435   /*                    @FT_FaceRec for the details.                       */
1436   /*                                                                       */
1437   /*    descender    :: The descender in 26.6 fractional pixels.  See      */
1438   /*                    @FT_FaceRec for the details.                       */
1439   /*                                                                       */
1440   /*    height       :: The height in 26.6 fractional pixels.  See         */
1441   /*                    @FT_FaceRec for the details.                       */
1442   /*                                                                       */
1443   /*    max_advance  :: The maximum advance width in 26.6 fractional       */
1444   /*                    pixels.  See @FT_FaceRec for the details.          */
1445   /*                                                                       */
1446   /* <Note>                                                                */
1447   /*    The scaling values, if relevant, are determined first during a     */
1448   /*    size changing operation.  The remaining fields are then set by the */
1449   /*    driver.  For scalable formats, they are usually set to scaled      */
1450   /*    values of the corresponding fields in @FT_FaceRec.                 */
1451   /*                                                                       */
1452   /*    Note that due to glyph hinting, these values might not be exact    */
1453   /*    for certain fonts.  Thus they must be treated as unreliable        */
1454   /*    with an error margin of at least one pixel!                        */
1455   /*                                                                       */
1456   /*    Indeed, the only way to get the exact metrics is to render _all_   */
1457   /*    glyphs.  As this would be a definite performance hit, it is up to  */
1458   /*    client applications to perform such computations.                  */
1459   /*                                                                       */
1460   /*    The FT_Size_Metrics structure is valid for bitmap fonts also.      */
1461   /*                                                                       */
1462   typedef struct  FT_Size_Metrics_
1463   {
1464     FT_UShort  x_ppem;      /* horizontal pixels per EM               */
1465     FT_UShort  y_ppem;      /* vertical pixels per EM                 */
1466
1467     FT_Fixed   x_scale;     /* scaling values used to convert font    */
1468     FT_Fixed   y_scale;     /* units to 26.6 fractional pixels        */
1469
1470     FT_Pos     ascender;    /* ascender in 26.6 frac. pixels          */
1471     FT_Pos     descender;   /* descender in 26.6 frac. pixels         */
1472     FT_Pos     height;      /* text height in 26.6 frac. pixels       */
1473     FT_Pos     max_advance; /* max horizontal advance, in 26.6 pixels */
1474
1475   } FT_Size_Metrics;
1476
1477
1478   /*************************************************************************/
1479   /*                                                                       */
1480   /* <Struct>                                                              */
1481   /*    FT_SizeRec                                                         */
1482   /*                                                                       */
1483   /* <Description>                                                         */
1484   /*    FreeType root size class structure.  A size object models a face   */
1485   /*    object at a given size.                                            */
1486   /*                                                                       */
1487   /* <Fields>                                                              */
1488   /*    face    :: Handle to the parent face object.                       */
1489   /*                                                                       */
1490   /*    generic :: A typeless pointer, unused by the FreeType library or   */
1491   /*               any of its drivers.  It can be used by client           */
1492   /*               applications to link their own data to each size        */
1493   /*               object.                                                 */
1494   /*                                                                       */
1495   /*    metrics :: Metrics for this size object.  This field is read-only. */
1496   /*                                                                       */
1497   typedef struct  FT_SizeRec_
1498   {
1499     FT_Face           face;      /* parent face object              */
1500     FT_Generic        generic;   /* generic pointer for client uses */
1501     FT_Size_Metrics   metrics;   /* size metrics                    */
1502     FT_Size_Internal  internal;
1503
1504   } FT_SizeRec;
1505
1506
1507   /*************************************************************************/
1508   /*                                                                       */
1509   /* <Struct>                                                              */
1510   /*    FT_SubGlyph                                                        */
1511   /*                                                                       */
1512   /* <Description>                                                         */
1513   /*    The subglyph structure is an internal object used to describe      */
1514   /*    subglyphs (for example, in the case of composites).                */
1515   /*                                                                       */
1516   /* <Note>                                                                */
1517   /*    The subglyph implementation is not part of the high-level API,     */
1518   /*    hence the forward structure declaration.                           */
1519   /*                                                                       */
1520   /*    You can however retrieve subglyph information with                 */
1521   /*    @FT_Get_SubGlyph_Info.                                             */
1522   /*                                                                       */
1523   typedef struct FT_SubGlyphRec_*  FT_SubGlyph;
1524
1525
1526   /*************************************************************************/
1527   /*                                                                       */
1528   /* <Type>                                                                */
1529   /*    FT_Slot_Internal                                                   */
1530   /*                                                                       */
1531   /* <Description>                                                         */
1532   /*    An opaque handle to an `FT_Slot_InternalRec' structure, used to    */
1533   /*    model private data of a given @FT_GlyphSlot object.                */
1534   /*                                                                       */
1535   typedef struct FT_Slot_InternalRec_*  FT_Slot_Internal;
1536
1537
1538   /*************************************************************************/
1539   /*                                                                       */
1540   /* <Struct>                                                              */
1541   /*    FT_GlyphSlotRec                                                    */
1542   /*                                                                       */
1543   /* <Description>                                                         */
1544   /*    FreeType root glyph slot class structure.  A glyph slot is a       */
1545   /*    container where individual glyphs can be loaded, be they in        */
1546   /*    outline or bitmap format.                                          */
1547   /*                                                                       */
1548   /* <Fields>                                                              */
1549   /*    library           :: A handle to the FreeType library instance     */
1550   /*                         this slot belongs to.                         */
1551   /*                                                                       */
1552   /*    face              :: A handle to the parent face object.           */
1553   /*                                                                       */
1554   /*    next              :: In some cases (like some font tools), several */
1555   /*                         glyph slots per face object can be a good     */
1556   /*                         thing.  As this is rare, the glyph slots are  */
1557   /*                         listed through a direct, single-linked list   */
1558   /*                         using its `next' field.                       */
1559   /*                                                                       */
1560   /*    generic           :: A typeless pointer unused by the FreeType     */
1561   /*                         library or any of its drivers.  It can be     */
1562   /*                         used by client applications to link their own */
1563   /*                         data to each glyph slot object.               */
1564   /*                                                                       */
1565   /*    metrics           :: The metrics of the last loaded glyph in the   */
1566   /*                         slot.  The returned values depend on the last */
1567   /*                         load flags (see the @FT_Load_Glyph API        */
1568   /*                         function) and can be expressed either in 26.6 */
1569   /*                         fractional pixels or font units.              */
1570   /*                                                                       */
1571   /*                         Note that even when the glyph image is        */
1572   /*                         transformed, the metrics are not.             */
1573   /*                                                                       */
1574   /*    linearHoriAdvance :: The advance width of the unhinted glyph.      */
1575   /*                         Its value is expressed in 16.16 fractional    */
1576   /*                         pixels, unless @FT_LOAD_LINEAR_DESIGN is set  */
1577   /*                         when loading the glyph.  This field can be    */
1578   /*                         important to perform correct WYSIWYG layout.  */
1579   /*                         Only relevant for outline glyphs.             */
1580   /*                                                                       */
1581   /*    linearVertAdvance :: The advance height of the unhinted glyph.     */
1582   /*                         Its value is expressed in 16.16 fractional    */
1583   /*                         pixels, unless @FT_LOAD_LINEAR_DESIGN is set  */
1584   /*                         when loading the glyph.  This field can be    */
1585   /*                         important to perform correct WYSIWYG layout.  */
1586   /*                         Only relevant for outline glyphs.             */
1587   /*                                                                       */
1588   /*    advance           :: This shorthand is, depending on               */
1589   /*                         @FT_LOAD_IGNORE_TRANSFORM, the transformed    */
1590   /*                         (hinted) advance width for the glyph, in 26.6 */
1591   /*                         fractional pixel format.  As specified with   */
1592   /*                         @FT_LOAD_VERTICAL_LAYOUT, it uses either the  */
1593   /*                         `horiAdvance' or the `vertAdvance' value of   */
1594   /*                         `metrics' field.                              */
1595   /*                                                                       */
1596   /*    format            :: This field indicates the format of the image  */
1597   /*                         contained in the glyph slot.  Typically       */
1598   /*                         @FT_GLYPH_FORMAT_BITMAP,                      */
1599   /*                         @FT_GLYPH_FORMAT_OUTLINE, or                  */
1600   /*                         @FT_GLYPH_FORMAT_COMPOSITE, but others are    */
1601   /*                         possible.                                     */
1602   /*                                                                       */
1603   /*    bitmap            :: This field is used as a bitmap descriptor     */
1604   /*                         when the slot format is                       */
1605   /*                         @FT_GLYPH_FORMAT_BITMAP.  Note that the       */
1606   /*                         address and content of the bitmap buffer can  */
1607   /*                         change between calls of @FT_Load_Glyph and a  */
1608   /*                         few other functions.                          */
1609   /*                                                                       */
1610   /*    bitmap_left       :: The bitmap's left bearing expressed in        */
1611   /*                         integer pixels.  Only valid if the format is  */
1612   /*                         @FT_GLYPH_FORMAT_BITMAP, this is, if the      */
1613   /*                         glyph slot contains a bitmap.                 */
1614   /*                                                                       */
1615   /*    bitmap_top        :: The bitmap's top bearing expressed in integer */
1616   /*                         pixels.  Remember that this is the distance   */
1617   /*                         from the baseline to the top-most glyph       */
1618   /*                         scanline, upwards y~coordinates being         */
1619   /*                         *positive*.                                   */
1620   /*                                                                       */
1621   /*    outline           :: The outline descriptor for the current glyph  */
1622   /*                         image if its format is                        */
1623   /*                         @FT_GLYPH_FORMAT_OUTLINE.  Once a glyph is    */
1624   /*                         loaded, `outline' can be transformed,         */
1625   /*                         distorted, embolded, etc.  However, it must   */
1626   /*                         not be freed.                                 */
1627   /*                                                                       */
1628   /*    num_subglyphs     :: The number of subglyphs in a composite glyph. */
1629   /*                         This field is only valid for the composite    */
1630   /*                         glyph format that should normally only be     */
1631   /*                         loaded with the @FT_LOAD_NO_RECURSE flag.     */
1632   /*                                                                       */
1633   /*    subglyphs         :: An array of subglyph descriptors for          */
1634   /*                         composite glyphs.  There are `num_subglyphs'  */
1635   /*                         elements in there.  Currently internal to     */
1636   /*                         FreeType.                                     */
1637   /*                                                                       */
1638   /*    control_data      :: Certain font drivers can also return the      */
1639   /*                         control data for a given glyph image (e.g.    */
1640   /*                         TrueType bytecode, Type~1 charstrings, etc.). */
1641   /*                         This field is a pointer to such data.         */
1642   /*                                                                       */
1643   /*    control_len       :: This is the length in bytes of the control    */
1644   /*                         data.                                         */
1645   /*                                                                       */
1646   /*    other             :: Really wicked formats can use this pointer to */
1647   /*                         present their own glyph image to client       */
1648   /*                         applications.  Note that the application      */
1649   /*                         needs to know about the image format.         */
1650   /*                                                                       */
1651   /*    lsb_delta         :: The difference between hinted and unhinted    */
1652   /*                         left side bearing while autohinting is        */
1653   /*                         active.  Zero otherwise.                      */
1654   /*                                                                       */
1655   /*    rsb_delta         :: The difference between hinted and unhinted    */
1656   /*                         right side bearing while autohinting is       */
1657   /*                         active.  Zero otherwise.                      */
1658   /*                                                                       */
1659   /* <Note>                                                                */
1660   /*    If @FT_Load_Glyph is called with default flags (see                */
1661   /*    @FT_LOAD_DEFAULT) the glyph image is loaded in the glyph slot in   */
1662   /*    its native format (e.g., an outline glyph for TrueType and Type~1  */
1663   /*    formats).                                                          */
1664   /*                                                                       */
1665   /*    This image can later be converted into a bitmap by calling         */
1666   /*    @FT_Render_Glyph.  This function finds the current renderer for    */
1667   /*    the native image's format, then invokes it.                        */
1668   /*                                                                       */
1669   /*    The renderer is in charge of transforming the native image through */
1670   /*    the slot's face transformation fields, then converting it into a   */
1671   /*    bitmap that is returned in `slot->bitmap'.                         */
1672   /*                                                                       */
1673   /*    Note that `slot->bitmap_left' and `slot->bitmap_top' are also used */
1674   /*    to specify the position of the bitmap relative to the current pen  */
1675   /*    position (e.g., coordinates (0,0) on the baseline).  Of course,    */
1676   /*    `slot->format' is also changed to @FT_GLYPH_FORMAT_BITMAP.         */
1677   /*                                                                       */
1678   /* <Note>                                                                */
1679   /*    Here a small pseudo code fragment that shows how to use            */
1680   /*    `lsb_delta' and `rsb_delta':                                       */
1681   /*                                                                       */
1682   /*    {                                                                  */
1683   /*      FT_Pos  origin_x       = 0;                                      */
1684   /*      FT_Pos  prev_rsb_delta = 0;                                      */
1685   /*                                                                       */
1686   /*                                                                       */
1687   /*      for all glyphs do                                                */
1688   /*        <compute kern between current and previous glyph and add it to */
1689   /*         `origin_x'>                                                   */
1690   /*                                                                       */
1691   /*        <load glyph with `FT_Load_Glyph'>                              */
1692   /*                                                                       */
1693   /*        if ( prev_rsb_delta - face->glyph->lsb_delta >= 32 )           */
1694   /*          origin_x -= 64;                                              */
1695   /*        else if ( prev_rsb_delta - face->glyph->lsb_delta < -32 )      */
1696   /*          origin_x += 64;                                              */
1697   /*                                                                       */
1698   /*        prev_rsb_delta = face->glyph->rsb_delta;                       */
1699   /*                                                                       */
1700   /*        <save glyph image, or render glyph, or ...>                    */
1701   /*                                                                       */
1702   /*        origin_x += face->glyph->advance.x;                            */
1703   /*      endfor                                                           */
1704   /*    }                                                                  */
1705   /*                                                                       */
1706   typedef struct  FT_GlyphSlotRec_
1707   {
1708     FT_Library        library;
1709     FT_Face           face;
1710     FT_GlyphSlot      next;
1711     FT_UInt           reserved;       /* retained for binary compatibility */
1712     FT_Generic        generic;
1713
1714     FT_Glyph_Metrics  metrics;
1715     FT_Fixed          linearHoriAdvance;
1716     FT_Fixed          linearVertAdvance;
1717     FT_Vector         advance;
1718
1719     FT_Glyph_Format   format;
1720
1721     FT_Bitmap         bitmap;
1722     FT_Int            bitmap_left;
1723     FT_Int            bitmap_top;
1724
1725     FT_Outline        outline;
1726
1727     FT_UInt           num_subglyphs;
1728     FT_SubGlyph       subglyphs;
1729
1730     void*             control_data;
1731     long              control_len;
1732
1733     FT_Pos            lsb_delta;
1734     FT_Pos            rsb_delta;
1735
1736     void*             other;
1737
1738     FT_Slot_Internal  internal;
1739
1740   } FT_GlyphSlotRec;
1741
1742
1743   /*************************************************************************/
1744   /*************************************************************************/
1745   /*                                                                       */
1746   /*                         F U N C T I O N S                             */
1747   /*                                                                       */
1748   /*************************************************************************/
1749   /*************************************************************************/
1750
1751
1752   /*************************************************************************/
1753   /*                                                                       */
1754   /* <Function>                                                            */
1755   /*    FT_Init_FreeType                                                   */
1756   /*                                                                       */
1757   /* <Description>                                                         */
1758   /*    Initialize a new FreeType library object.  The set of modules      */
1759   /*    that are registered by this function is determined at build time.  */
1760   /*                                                                       */
1761   /* <Output>                                                              */
1762   /*    alibrary :: A handle to a new library object.                      */
1763   /*                                                                       */
1764   /* <Return>                                                              */
1765   /*    FreeType error code.  0~means success.                             */
1766   /*                                                                       */
1767   /* <Note>                                                                */
1768   /*    In case you want to provide your own memory allocating routines,   */
1769   /*    use @FT_New_Library instead, followed by a call to                 */
1770   /*    @FT_Add_Default_Modules (or a series of calls to @FT_Add_Module).  */
1771   /*                                                                       */
1772   /*    For multi-threading applications each thread should have its own   */
1773   /*    FT_Library object.                                                 */
1774   /*                                                                       */
1775   /*    If you need reference-counting (cf. @FT_Reference_Library), use    */
1776   /*    @FT_New_Library and @FT_Done_Library.                              */
1777   /*                                                                       */
1778   FT_EXPORT( FT_Error )
1779   FT_Init_FreeType( FT_Library  *alibrary );
1780
1781
1782   /*************************************************************************/
1783   /*                                                                       */
1784   /* <Function>                                                            */
1785   /*    FT_Done_FreeType                                                   */
1786   /*                                                                       */
1787   /* <Description>                                                         */
1788   /*    Destroy a given FreeType library object and all of its children,   */
1789   /*    including resources, drivers, faces, sizes, etc.                   */
1790   /*                                                                       */
1791   /* <Input>                                                               */
1792   /*    library :: A handle to the target library object.                  */
1793   /*                                                                       */
1794   /* <Return>                                                              */
1795   /*    FreeType error code.  0~means success.                             */
1796   /*                                                                       */
1797   FT_EXPORT( FT_Error )
1798   FT_Done_FreeType( FT_Library  library );
1799
1800
1801   /*************************************************************************/
1802   /*                                                                       */
1803   /* <Enum>                                                                */
1804   /*    FT_OPEN_XXX                                                        */
1805   /*                                                                       */
1806   /* <Description>                                                         */
1807   /*    A list of bit-field constants used within the `flags' field of the */
1808   /*    @FT_Open_Args structure.                                           */
1809   /*                                                                       */
1810   /* <Values>                                                              */
1811   /*    FT_OPEN_MEMORY   :: This is a memory-based stream.                 */
1812   /*                                                                       */
1813   /*    FT_OPEN_STREAM   :: Copy the stream from the `stream' field.       */
1814   /*                                                                       */
1815   /*    FT_OPEN_PATHNAME :: Create a new input stream from a C~path        */
1816   /*                        name.                                          */
1817   /*                                                                       */
1818   /*    FT_OPEN_DRIVER   :: Use the `driver' field.                        */
1819   /*                                                                       */
1820   /*    FT_OPEN_PARAMS   :: Use the `num_params' and `params' fields.      */
1821   /*                                                                       */
1822   /* <Note>                                                                */
1823   /*    The `FT_OPEN_MEMORY', `FT_OPEN_STREAM', and `FT_OPEN_PATHNAME'     */
1824   /*    flags are mutually exclusive.                                      */
1825   /*                                                                       */
1826 #define FT_OPEN_MEMORY    0x1
1827 #define FT_OPEN_STREAM    0x2
1828 #define FT_OPEN_PATHNAME  0x4
1829 #define FT_OPEN_DRIVER    0x8
1830 #define FT_OPEN_PARAMS    0x10
1831
1832
1833   /* these constants are deprecated; use the corresponding `FT_OPEN_XXX' */
1834   /* values instead                                                      */
1835 #define ft_open_memory    FT_OPEN_MEMORY
1836 #define ft_open_stream    FT_OPEN_STREAM
1837 #define ft_open_pathname  FT_OPEN_PATHNAME
1838 #define ft_open_driver    FT_OPEN_DRIVER
1839 #define ft_open_params    FT_OPEN_PARAMS
1840
1841
1842   /*************************************************************************/
1843   /*                                                                       */
1844   /* <Struct>                                                              */
1845   /*    FT_Parameter                                                       */
1846   /*                                                                       */
1847   /* <Description>                                                         */
1848   /*    A simple structure used to pass more or less generic parameters to */
1849   /*    @FT_Open_Face.                                                     */
1850   /*                                                                       */
1851   /* <Fields>                                                              */
1852   /*    tag  :: A four-byte identification tag.                            */
1853   /*                                                                       */
1854   /*    data :: A pointer to the parameter data.                           */
1855   /*                                                                       */
1856   /* <Note>                                                                */
1857   /*    The ID and function of parameters are driver-specific.  See the    */
1858   /*    various FT_PARAM_TAG_XXX flags for more information.               */
1859   /*                                                                       */
1860   typedef struct  FT_Parameter_
1861   {
1862     FT_ULong    tag;
1863     FT_Pointer  data;
1864
1865   } FT_Parameter;
1866
1867
1868   /*************************************************************************/
1869   /*                                                                       */
1870   /* <Struct>                                                              */
1871   /*    FT_Open_Args                                                       */
1872   /*                                                                       */
1873   /* <Description>                                                         */
1874   /*    A structure used to indicate how to open a new font file or        */
1875   /*    stream.  A pointer to such a structure can be used as a parameter  */
1876   /*    for the functions @FT_Open_Face and @FT_Attach_Stream.             */
1877   /*                                                                       */
1878   /* <Fields>                                                              */
1879   /*    flags       :: A set of bit flags indicating how to use the        */
1880   /*                   structure.                                          */
1881   /*                                                                       */
1882   /*    memory_base :: The first byte of the file in memory.               */
1883   /*                                                                       */
1884   /*    memory_size :: The size in bytes of the file in memory.            */
1885   /*                                                                       */
1886   /*    pathname    :: A pointer to an 8-bit file pathname.                */
1887   /*                                                                       */
1888   /*    stream      :: A handle to a source stream object.                 */
1889   /*                                                                       */
1890   /*    driver      :: This field is exclusively used by @FT_Open_Face;    */
1891   /*                   it simply specifies the font driver to use to open  */
1892   /*                   the face.  If set to~0, FreeType tries to load the  */
1893   /*                   face with each one of the drivers in its list.      */
1894   /*                                                                       */
1895   /*    num_params  :: The number of extra parameters.                     */
1896   /*                                                                       */
1897   /*    params      :: Extra parameters passed to the font driver when     */
1898   /*                   opening a new face.                                 */
1899   /*                                                                       */
1900   /* <Note>                                                                */
1901   /*    The stream type is determined by the contents of `flags' that      */
1902   /*    are tested in the following order by @FT_Open_Face:                */
1903   /*                                                                       */
1904   /*    If the @FT_OPEN_MEMORY bit is set, assume that this is a           */
1905   /*    memory file of `memory_size' bytes, located at `memory_address'.   */
1906   /*    The data are are not copied, and the client is responsible for     */
1907   /*    releasing and destroying them _after_ the corresponding call to    */
1908   /*    @FT_Done_Face.                                                     */
1909   /*                                                                       */
1910   /*    Otherwise, if the @FT_OPEN_STREAM bit is set, assume that a        */
1911   /*    custom input stream `stream' is used.                              */
1912   /*                                                                       */
1913   /*    Otherwise, if the @FT_OPEN_PATHNAME bit is set, assume that this   */
1914   /*    is a normal file and use `pathname' to open it.                    */
1915   /*                                                                       */
1916   /*    If the @FT_OPEN_DRIVER bit is set, @FT_Open_Face only tries to     */
1917   /*    open the file with the driver whose handler is in `driver'.        */
1918   /*                                                                       */
1919   /*    If the @FT_OPEN_PARAMS bit is set, the parameters given by         */
1920   /*    `num_params' and `params' is used.  They are ignored otherwise.    */
1921   /*                                                                       */
1922   /*    Ideally, both the `pathname' and `params' fields should be tagged  */
1923   /*    as `const'; this is missing for API backwards compatibility.  In   */
1924   /*    other words, applications should treat them as read-only.          */
1925   /*                                                                       */
1926   typedef struct  FT_Open_Args_
1927   {
1928     FT_UInt         flags;
1929     const FT_Byte*  memory_base;
1930     FT_Long         memory_size;
1931     FT_String*      pathname;
1932     FT_Stream       stream;
1933     FT_Module       driver;
1934     FT_Int          num_params;
1935     FT_Parameter*   params;
1936
1937   } FT_Open_Args;
1938
1939
1940   /*************************************************************************/
1941   /*                                                                       */
1942   /* <Function>                                                            */
1943   /*    FT_New_Face                                                        */
1944   /*                                                                       */
1945   /* <Description>                                                         */
1946   /*    This function calls @FT_Open_Face to open a font by its pathname.  */
1947   /*                                                                       */
1948   /* <InOut>                                                               */
1949   /*    library    :: A handle to the library resource.                    */
1950   /*                                                                       */
1951   /* <Input>                                                               */
1952   /*    pathname   :: A path to the font file.                             */
1953   /*                                                                       */
1954   /*    face_index :: The index of the face within the font.  The first    */
1955   /*                  face has index~0.                                    */
1956   /*                                                                       */
1957   /* <Output>                                                              */
1958   /*    aface      :: A handle to a new face object.  If `face_index' is   */
1959   /*                  greater than or equal to zero, it must be non-NULL.  */
1960   /*                  See @FT_Open_Face for more details.                  */
1961   /*                                                                       */
1962   /* <Return>                                                              */
1963   /*    FreeType error code.  0~means success.                             */
1964   /*                                                                       */
1965   /* <Note>                                                                */
1966   /*    Use @FT_Done_Face to destroy the created @FT_Face object (along    */
1967   /*    with its slot and sizes).                                          */
1968   /*                                                                       */
1969   FT_EXPORT( FT_Error )
1970   FT_New_Face( FT_Library   library,
1971                const char*  filepathname,
1972                FT_Long      face_index,
1973                FT_Face     *aface );
1974
1975
1976   /*************************************************************************/
1977   /*                                                                       */
1978   /* <Function>                                                            */
1979   /*    FT_New_Memory_Face                                                 */
1980   /*                                                                       */
1981   /* <Description>                                                         */
1982   /*    This function calls @FT_Open_Face to open a font that has been     */
1983   /*    loaded into memory.                                                */
1984   /*                                                                       */
1985   /* <InOut>                                                               */
1986   /*    library    :: A handle to the library resource.                    */
1987   /*                                                                       */
1988   /* <Input>                                                               */
1989   /*    file_base  :: A pointer to the beginning of the font data.         */
1990   /*                                                                       */
1991   /*    file_size  :: The size of the memory chunk used by the font data.  */
1992   /*                                                                       */
1993   /*    face_index :: The index of the face within the font.  The first    */
1994   /*                  face has index~0.                                    */
1995   /*                                                                       */
1996   /* <Output>                                                              */
1997   /*    aface      :: A handle to a new face object.  If `face_index' is   */
1998   /*                  greater than or equal to zero, it must be non-NULL.  */
1999   /*                  See @FT_Open_Face for more details.                  */
2000   /*                                                                       */
2001   /* <Return>                                                              */
2002   /*    FreeType error code.  0~means success.                             */
2003   /*                                                                       */
2004   /* <Note>                                                                */
2005   /*    You must not deallocate the memory before calling @FT_Done_Face.   */
2006   /*                                                                       */
2007   FT_EXPORT( FT_Error )
2008   FT_New_Memory_Face( FT_Library      library,
2009                       const FT_Byte*  file_base,
2010                       FT_Long         file_size,
2011                       FT_Long         face_index,
2012                       FT_Face        *aface );
2013
2014
2015   /*************************************************************************/
2016   /*                                                                       */
2017   /* <Function>                                                            */
2018   /*    FT_Open_Face                                                       */
2019   /*                                                                       */
2020   /* <Description>                                                         */
2021   /*    Create a face object from a given resource described by            */
2022   /*    @FT_Open_Args.                                                     */
2023   /*                                                                       */
2024   /* <InOut>                                                               */
2025   /*    library    :: A handle to the library resource.                    */
2026   /*                                                                       */
2027   /* <Input>                                                               */
2028   /*    args       :: A pointer to an `FT_Open_Args' structure that must   */
2029   /*                  be filled by the caller.                             */
2030   /*                                                                       */
2031   /*    face_index :: The index of the face within the font.  The first    */
2032   /*                  face has index~0.                                    */
2033   /*                                                                       */
2034   /* <Output>                                                              */
2035   /*    aface      :: A handle to a new face object.  If `face_index' is   */
2036   /*                  greater than or equal to zero, it must be non-NULL.  */
2037   /*                  See note below.                                      */
2038   /*                                                                       */
2039   /* <Return>                                                              */
2040   /*    FreeType error code.  0~means success.                             */
2041   /*                                                                       */
2042   /* <Note>                                                                */
2043   /*    Unlike FreeType 1.x, this function automatically creates a glyph   */
2044   /*    slot for the face object that can be accessed directly through     */
2045   /*    `face->glyph'.                                                     */
2046   /*                                                                       */
2047   /*    FT_Open_Face can be used to quickly check whether the font         */
2048   /*    format of a given font resource is supported by FreeType.  If the  */
2049   /*    `face_index' field is negative, the function's return value is~0   */
2050   /*    if the font format is recognized, or non-zero otherwise;           */
2051   /*    the function returns a more or less empty face handle in `*aface'  */
2052   /*    (if `aface' isn't NULL).  The only useful field in this special    */
2053   /*    case is `face->num_faces' that gives the number of faces within    */
2054   /*    the font file.  After examination, the returned @FT_Face structure */
2055   /*    should be deallocated with a call to @FT_Done_Face.                */
2056   /*                                                                       */
2057   /*    Each new face object created with this function also owns a        */
2058   /*    default @FT_Size object, accessible as `face->size'.               */
2059   /*                                                                       */
2060   /*    One @FT_Library instance can have multiple face objects, this is,  */
2061   /*    @FT_Open_Face and its siblings can be called multiple times using  */
2062   /*    the same `library' argument.                                       */
2063   /*                                                                       */
2064   /*    See the discussion of reference counters in the description of     */
2065   /*    @FT_Reference_Face.                                                */
2066   /*                                                                       */
2067   FT_EXPORT( FT_Error )
2068   FT_Open_Face( FT_Library           library,
2069                 const FT_Open_Args*  args,
2070                 FT_Long              face_index,
2071                 FT_Face             *aface );
2072
2073
2074   /*************************************************************************/
2075   /*                                                                       */
2076   /* <Function>                                                            */
2077   /*    FT_Attach_File                                                     */
2078   /*                                                                       */
2079   /* <Description>                                                         */
2080   /*    This function calls @FT_Attach_Stream to attach a file.            */
2081   /*                                                                       */
2082   /* <InOut>                                                               */
2083   /*    face         :: The target face object.                            */
2084   /*                                                                       */
2085   /* <Input>                                                               */
2086   /*    filepathname :: The pathname.                                      */
2087   /*                                                                       */
2088   /* <Return>                                                              */
2089   /*    FreeType error code.  0~means success.                             */
2090   /*                                                                       */
2091   FT_EXPORT( FT_Error )
2092   FT_Attach_File( FT_Face      face,
2093                   const char*  filepathname );
2094
2095
2096   /*************************************************************************/
2097   /*                                                                       */
2098   /* <Function>                                                            */
2099   /*    FT_Attach_Stream                                                   */
2100   /*                                                                       */
2101   /* <Description>                                                         */
2102   /*    `Attach' data to a face object.  Normally, this is used to read    */
2103   /*    additional information for the face object.  For example, you can  */
2104   /*    attach an AFM file that comes with a Type~1 font to get the        */
2105   /*    kerning values and other metrics.                                  */
2106   /*                                                                       */
2107   /* <InOut>                                                               */
2108   /*    face       :: The target face object.                              */
2109   /*                                                                       */
2110   /* <Input>                                                               */
2111   /*    parameters :: A pointer to @FT_Open_Args that must be filled by    */
2112   /*                  the caller.                                          */
2113   /*                                                                       */
2114   /* <Return>                                                              */
2115   /*    FreeType error code.  0~means success.                             */
2116   /*                                                                       */
2117   /* <Note>                                                                */
2118   /*    The meaning of the `attach' (i.e., what really happens when the    */
2119   /*    new file is read) is not fixed by FreeType itself.  It really      */
2120   /*    depends on the font format (and thus the font driver).             */
2121   /*                                                                       */
2122   /*    Client applications are expected to know what they are doing       */
2123   /*    when invoking this function.  Most drivers simply do not implement */
2124   /*    file attachments.                                                  */
2125   /*                                                                       */
2126   FT_EXPORT( FT_Error )
2127   FT_Attach_Stream( FT_Face        face,
2128                     FT_Open_Args*  parameters );
2129
2130
2131   /*************************************************************************/
2132   /*                                                                       */
2133   /* <Function>                                                            */
2134   /*    FT_Reference_Face                                                  */
2135   /*                                                                       */
2136   /* <Description>                                                         */
2137   /*    A counter gets initialized to~1 at the time an @FT_Face structure  */
2138   /*    is created.  This function increments the counter.  @FT_Done_Face  */
2139   /*    then only destroys a face if the counter is~1, otherwise it simply */
2140   /*    decrements the counter.                                            */
2141   /*                                                                       */
2142   /*    This function helps in managing life-cycles of structures that     */
2143   /*    reference @FT_Face objects.                                        */
2144   /*                                                                       */
2145   /* <Input>                                                               */
2146   /*    face :: A handle to a target face object.                          */
2147   /*                                                                       */
2148   /* <Return>                                                              */
2149   /*    FreeType error code.  0~means success.                             */
2150   /*                                                                       */
2151   /* <Since>                                                               */
2152   /*    2.4.2                                                              */
2153   /*                                                                       */
2154   FT_EXPORT( FT_Error )
2155   FT_Reference_Face( FT_Face  face );
2156
2157
2158   /*************************************************************************/
2159   /*                                                                       */
2160   /* <Function>                                                            */
2161   /*    FT_Done_Face                                                       */
2162   /*                                                                       */
2163   /* <Description>                                                         */
2164   /*    Discard a given face object, as well as all of its child slots and */
2165   /*    sizes.                                                             */
2166   /*                                                                       */
2167   /* <Input>                                                               */
2168   /*    face :: A handle to a target face object.                          */
2169   /*                                                                       */
2170   /* <Return>                                                              */
2171   /*    FreeType error code.  0~means success.                             */
2172   /*                                                                       */
2173   /* <Note>                                                                */
2174   /*    See the discussion of reference counters in the description of     */
2175   /*    @FT_Reference_Face.                                                */
2176   /*                                                                       */
2177   FT_EXPORT( FT_Error )
2178   FT_Done_Face( FT_Face  face );
2179
2180
2181   /*************************************************************************/
2182   /*                                                                       */
2183   /* <Function>                                                            */
2184   /*    FT_Select_Size                                                     */
2185   /*                                                                       */
2186   /* <Description>                                                         */
2187   /*    Select a bitmap strike.                                            */
2188   /*                                                                       */
2189   /* <InOut>                                                               */
2190   /*    face         :: A handle to a target face object.                  */