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