source: trunk/poppler/freetype-2.1.10/include/freetype/freetype.h @ 2

Last change on this file since 2 was 2, checked in by Eugene Romanenko, 16 years ago

First import

File size: 196.7 KB
Line 
1/***************************************************************************/
2/*                                                                         */
3/*  freetype.h                                                             */
4/*                                                                         */
5/*    FreeType high-level API and common types (specification only).       */
6/*                                                                         */
7/*  Copyright 1996-2001, 2002, 2003, 2004, 2005 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 FT_FREETYPE_H
20#error "`ft2build.h' hasn't been included yet!"
21#error "Please always use macros to include FreeType header files."
22#error "Example:"
23#error "  #include <ft2build.h>"
24#error "  #include FT_FREETYPE_H"
25#endif
26
27
28#ifndef __FREETYPE_H__
29#define __FREETYPE_H__
30
31
32  /*************************************************************************/
33  /*                                                                       */
34  /* The `raster' component duplicates some of the declarations in         */
35  /* freetype.h for stand-alone use if _FREETYPE_ isn't defined.           */
36  /*                                                                       */
37
38
39  /*************************************************************************/
40  /*                                                                       */
41  /* The FREETYPE_MAJOR and FREETYPE_MINOR macros are used to version the  */
42  /* new FreeType design, which is able to host several kinds of font      */
43  /* drivers.  It starts at 2.0.                                           */
44  /*                                                                       */
45#define FREETYPE_MAJOR 2
46#define FREETYPE_MINOR 1
47#define FREETYPE_PATCH 10
48
49
50#include <ft2build.h>
51#include FT_CONFIG_CONFIG_H
52#include FT_ERRORS_H
53#include FT_TYPES_H
54
55
56FT_BEGIN_HEADER
57
58
59  /*************************************************************************/
60  /*************************************************************************/
61  /*                                                                       */
62  /*                        B A S I C   T Y P E S                          */
63  /*                                                                       */
64  /*************************************************************************/
65  /*************************************************************************/
66
67
68  /*************************************************************************/
69  /*                                                                       */
70  /* <Section>                                                             */
71  /*    base_interface                                                     */
72  /*                                                                       */
73  /* <Title>                                                               */
74  /*    Base Interface                                                     */
75  /*                                                                       */
76  /* <Abstract>                                                            */
77  /*    The FreeType 2 base font interface.                                */
78  /*                                                                       */
79  /* <Description>                                                         */
80  /*    This section describes the public high-level API of FreeType 2.    */
81  /*                                                                       */
82  /* <Order>                                                               */
83  /*    FT_Library                                                         */
84  /*    FT_Face                                                            */
85  /*    FT_Size                                                            */
86  /*    FT_GlyphSlot                                                       */
87  /*    FT_CharMap                                                         */
88  /*    FT_Encoding                                                        */
89  /*                                                                       */
90  /*    FT_FaceRec                                                         */
91  /*                                                                       */
92  /*    FT_FACE_FLAG_SCALABLE                                              */
93  /*    FT_FACE_FLAG_FIXED_SIZES                                           */
94  /*    FT_FACE_FLAG_FIXED_WIDTH                                           */
95  /*    FT_FACE_FLAG_HORIZONTAL                                            */
96  /*    FT_FACE_FLAG_VERTICAL                                              */
97  /*    FT_FACE_FLAG_SFNT                                                  */
98  /*    FT_FACE_FLAG_KERNING                                               */
99  /*    FT_FACE_FLAG_MULTIPLE_MASTERS                                      */
100  /*    FT_FACE_FLAG_GLYPH_NAMES                                           */
101  /*    FT_FACE_FLAG_EXTERNAL_STREAM                                       */
102  /*    FT_FACE_FLAG_FAST_GLYPHS                                           */
103  /*                                                                       */
104  /*    FT_STYLE_FLAG_BOLD                                                 */
105  /*    FT_STYLE_FLAG_ITALIC                                               */
106  /*                                                                       */
107  /*    FT_SizeRec                                                         */
108  /*    FT_Size_Metrics                                                    */
109  /*                                                                       */
110  /*    FT_GlyphSlotRec                                                    */
111  /*    FT_Glyph_Metrics                                                   */
112  /*    FT_SubGlyph                                                        */
113  /*                                                                       */
114  /*    FT_Bitmap_Size                                                     */
115  /*                                                                       */
116  /*    FT_Init_FreeType                                                   */
117  /*    FT_Done_FreeType                                                   */
118  /*    FT_Library_Version                                                 */
119  /*                                                                       */
120  /*    FT_New_Face                                                        */
121  /*    FT_Done_Face                                                       */
122  /*    FT_New_Memory_Face                                                 */
123  /*    FT_Open_Face                                                       */
124  /*    FT_Open_Args                                                       */
125  /*    FT_Parameter                                                       */
126  /*    FT_Attach_File                                                     */
127  /*    FT_Attach_Stream                                                   */
128  /*                                                                       */
129  /*    FT_Set_Char_Size                                                   */
130  /*    FT_Set_Pixel_Sizes                                                 */
131  /*    FT_Set_Transform                                                   */
132  /*    FT_Load_Glyph                                                      */
133  /*    FT_Get_Char_Index                                                  */
134  /*    FT_Get_Name_Index                                                  */
135  /*    FT_Load_Char                                                       */
136  /*                                                                       */
137  /*    FT_OPEN_MEMORY                                                     */
138  /*    FT_OPEN_STREAM                                                     */
139  /*    FT_OPEN_PATHNAME                                                   */
140  /*    FT_OPEN_DRIVER                                                     */
141  /*    FT_OPEN_PARAMS                                                     */
142  /*                                                                       */
143  /*    FT_LOAD_DEFAULT                                                    */
144  /*    FT_LOAD_RENDER                                                     */
145  /*    FT_LOAD_MONOCHROME                                                 */
146  /*    FT_LOAD_LINEAR_DESIGN                                              */
147  /*    FT_LOAD_NO_SCALE                                                   */
148  /*    FT_LOAD_NO_HINTING                                                 */
149  /*    FT_LOAD_NO_BITMAP                                                  */
150  /*    FT_LOAD_CROP_BITMAP                                                */
151  /*                                                                       */
152  /*    FT_LOAD_VERTICAL_LAYOUT                                            */
153  /*    FT_LOAD_IGNORE_TRANSFORM                                           */
154  /*    FT_LOAD_IGNORE_GLOBAL_ADVANCE_WIDTH                                */
155  /*    FT_LOAD_FORCE_AUTOHINT                                             */
156  /*    FT_LOAD_NO_RECURSE                                                 */
157  /*    FT_LOAD_PEDANTIC                                                   */
158  /*                                                                       */
159  /*    FT_LOAD_TARGET_NORMAL                                              */
160  /*    FT_LOAD_TARGET_LIGHT                                               */
161  /*    FT_LOAD_TARGET_MONO                                                */
162  /*    FT_LOAD_TARGET_LCD                                                 */
163  /*    FT_LOAD_TARGET_LCD_V                                               */
164  /*                                                                       */
165  /*    FT_Render_Glyph                                                    */
166  /*    FT_Render_Mode                                                     */
167  /*    FT_Get_Kerning                                                     */
168  /*    FT_Kerning_Mode                                                    */
169  /*    FT_Get_Glyph_Name                                                  */
170  /*    FT_Get_Postscript_Name                                             */
171  /*                                                                       */
172  /*    FT_CharMapRec                                                      */
173  /*    FT_Select_Charmap                                                  */
174  /*    FT_Set_Charmap                                                     */
175  /*    FT_Get_Charmap_Index                                               */
176  /*                                                                       */
177  /*************************************************************************/
178
179
180  /*************************************************************************/
181  /*                                                                       */
182  /* <Struct>                                                              */
183  /*    FT_Glyph_Metrics                                                   */
184  /*                                                                       */
185  /* <Description>                                                         */
186  /*    A structure used to model the metrics of a single glyph.  The      */
187  /*    values are expressed in 26.6 fractional pixel format; if the flag  */
188  /*    FT_LOAD_NO_SCALE is used, values are returned in font units        */
189  /*    instead.                                                           */
190  /*                                                                       */
191  /* <Fields>                                                              */
192  /*    width ::                                                           */
193  /*      The glyph's width.                                               */
194  /*                                                                       */
195  /*    height ::                                                          */
196  /*      The glyph's height.                                              */
197  /*                                                                       */
198  /*    horiBearingX ::                                                    */
199  /*      Left side bearing for horizontal layout.                         */
200  /*                                                                       */
201  /*    horiBearingY ::                                                    */
202  /*      Top side bearing for horizontal layout.                          */
203  /*                                                                       */
204  /*    horiAdvance ::                                                     */
205  /*      Advance width for horizontal layout.                             */
206  /*                                                                       */
207  /*    vertBearingX ::                                                    */
208  /*      Left side bearing for vertical layout.                           */
209  /*                                                                       */
210  /*    vertBearingY ::                                                    */
211  /*      Top side bearing for vertical layout.                            */
212  /*                                                                       */
213  /*    vertAdvance ::                                                     */
214  /*      Advance height for vertical layout.                              */
215  /*                                                                       */
216  typedef struct  FT_Glyph_Metrics_
217  {
218    FT_Pos  width;
219    FT_Pos  height;
220
221    FT_Pos  horiBearingX;
222    FT_Pos  horiBearingY;
223    FT_Pos  horiAdvance;
224
225    FT_Pos  vertBearingX;
226    FT_Pos  vertBearingY;
227    FT_Pos  vertAdvance;
228
229  } FT_Glyph_Metrics;
230
231
232  /*************************************************************************/
233  /*                                                                       */
234  /* <Struct>                                                              */
235  /*    FT_Bitmap_Size                                                     */
236  /*                                                                       */
237  /* <Description>                                                         */
238  /*    This structure models the size of a bitmap strike (i.e., a bitmap  */
239  /*    instance of the font for a given resolution) in a fixed-size font  */
240  /*    face.  It is used for the `available_sizes' field of the           */
241  /*    @FT_FaceRec structure.                                             */
242  /*                                                                       */
243  /* <Fields>                                                              */
244  /*    height :: The (vertical) baseline-to-baseline distance in pixels.  */
245  /*              It makes most sense to define the height of a bitmap     */
246  /*              font in this way.                                        */
247  /*                                                                       */
248  /*    width  :: The average width of the font (in pixels).  Since the    */
249  /*              algorithms to compute this value are different for the   */
250  /*              various bitmap formats, it can only give an additional   */
251  /*              hint if the `height' value isn't sufficient to select    */
252  /*              the proper font.  For monospaced fonts the average width */
253  /*              is the same as the maximum width.                        */
254  /*                                                                       */
255  /*    size   :: The point size in 26.6 fractional format this font shall */
256  /*              represent (for a given vertical resolution).             */
257  /*                                                                       */
258  /*    x_ppem :: The horizontal ppem value (in 26.6 fractional format).   */
259  /*                                                                       */
260  /*    y_ppem :: The vertical ppem value (in 26.6 fractional format).     */
261  /*              Usually, this is the `nominal' pixel height of the font. */
262  /*                                                                       */
263  /* <Note>                                                                */
264  /*    The values in this structure are taken from the bitmap font.  If   */
265  /*    the font doesn't provide a parameter it is set to zero to indicate */
266  /*    that the information is not available.                             */
267  /*                                                                       */
268  /*    The following formula converts from dpi to ppem:                   */
269  /*                                                                       */
270  /*      ppem = size * dpi / 72                                           */
271  /*                                                                       */
272  /*    where `size' is in points.                                         */
273  /*                                                                       */
274  /*    Windows FNT:                                                       */
275  /*      The `size' parameter is not reliable: There exist fonts (e.g.,   */
276  /*      app850.fon) which have a wrong size for some subfonts; x_ppem    */
277  /*      and y_ppem are thus set equal to pixel width and height given in */
278  /*      in the Windows FNT header.                                       */
279  /*                                                                       */
280  /*    TrueType embedded bitmaps:                                         */
281  /*      `size', `width', and `height' values are not contained in the    */
282  /*      bitmap strike itself.  They are computed from the global font    */
283  /*      parameters.                                                      */
284  /*                                                                       */
285  typedef struct  FT_Bitmap_Size_
286  {
287    FT_Short  height;
288    FT_Short  width;
289
290    FT_Pos    size;
291
292    FT_Pos    x_ppem;
293    FT_Pos    y_ppem;
294
295  } FT_Bitmap_Size;
296
297
298  /*************************************************************************/
299  /*************************************************************************/
300  /*                                                                       */
301  /*                     O B J E C T   C L A S S E S                       */
302  /*                                                                       */
303  /*************************************************************************/
304  /*************************************************************************/
305
306  /*************************************************************************/
307  /*                                                                       */
308  /* <Type>                                                                */
309  /*    FT_Library                                                         */
310  /*                                                                       */
311  /* <Description>                                                         */
312  /*    A handle to a FreeType library instance.  Each `library' is        */
313  /*    completely independent from the others; it is the `root' of a set  */
314  /*    of objects like fonts, faces, sizes, etc.                          */
315  /*                                                                       */
316  /*    It also embeds a memory manager (see @FT_Memory), as well as a     */
317  /*    scan-line converter object (see @FT_Raster).                       */
318  /*                                                                       */
319  /* <Note>                                                                */
320  /*    Library objects are normally created by @FT_Init_FreeType, and     */
321  /*    destroyed with @FT_Done_FreeType.                                  */
322  /*                                                                       */
323  typedef struct FT_LibraryRec_  *FT_Library;
324
325
326  /*************************************************************************/
327  /*                                                                       */
328  /* <Type>                                                                */
329  /*    FT_Module                                                          */
330  /*                                                                       */
331  /* <Description>                                                         */
332  /*    A handle to a given FreeType module object.  Each module can be a  */
333  /*    font driver, a renderer, or anything else that provides services   */
334  /*    to the formers.                                                    */
335  /*                                                                       */
336  typedef struct FT_ModuleRec_*  FT_Module;
337
338
339  /*************************************************************************/
340  /*                                                                       */
341  /* <Type>                                                                */
342  /*    FT_Driver                                                          */
343  /*                                                                       */
344  /* <Description>                                                         */
345  /*    A handle to a given FreeType font driver object.  Each font driver */
346  /*    is a special module capable of creating faces from font files.     */
347  /*                                                                       */
348  typedef struct FT_DriverRec_*  FT_Driver;
349
350
351  /*************************************************************************/
352  /*                                                                       */
353  /* <Type>                                                                */
354  /*    FT_Renderer                                                        */
355  /*                                                                       */
356  /* <Description>                                                         */
357  /*    A handle to a given FreeType renderer.  A renderer is a special    */
358  /*    module in charge of converting a glyph image to a bitmap, when     */
359  /*    necessary.  Each renderer supports a given glyph image format, and */
360  /*    one or more target surface depths.                                 */
361  /*                                                                       */
362  typedef struct FT_RendererRec_*  FT_Renderer;
363
364
365  /*************************************************************************/
366  /*                                                                       */
367  /* <Type>                                                                */
368  /*    FT_Face                                                            */
369  /*                                                                       */
370  /* <Description>                                                         */
371  /*    A handle to a given typographic face object.  A face object models */
372  /*    a given typeface, in a given style.                                */
373  /*                                                                       */
374  /* <Note>                                                                */
375  /*    Each face object also owns a single @FT_GlyphSlot object, as well  */
376  /*    as one or more @FT_Size objects.                                   */
377  /*                                                                       */
378  /*    Use @FT_New_Face or @FT_Open_Face to create a new face object from */
379  /*    a given filepathname or a custom input stream.                     */
380  /*                                                                       */
381  /*    Use @FT_Done_Face to destroy it (along with its slot and sizes).   */
382  /*                                                                       */
383  /* <Also>                                                                */
384  /*    The @FT_FaceRec details the publicly accessible fields of a given  */
385  /*    face object.                                                       */
386  /*                                                                       */
387  typedef struct FT_FaceRec_*  FT_Face;
388
389
390  /*************************************************************************/
391  /*                                                                       */
392  /* <Type>                                                                */
393  /*    FT_Size                                                            */
394  /*                                                                       */
395  /* <Description>                                                         */
396  /*    A handle to a given size object.  Such an object models the data   */
397  /*    that depends on the current _resolution_ and _character size_ in a */
398  /*    given @FT_Face.                                                    */
399  /*                                                                       */
400  /* <Note>                                                                */
401  /*    Each face object owns one or more sizes.  There is however a       */
402  /*    single _active_ size for the face at any time that will be used by */
403  /*    functions like @FT_Load_Glyph, @FT_Get_Kerning, etc.               */
404  /*                                                                       */
405  /*    You can use the @FT_Activate_Size API to change the current        */
406  /*    active size of any given face.                                     */
407  /*                                                                       */
408  /* <Also>                                                                */
409  /*    The @FT_SizeRec structure details the publicly accessible fields   */
410  /*    of a given face object.                                            */
411  /*                                                                       */
412  typedef struct FT_SizeRec_*  FT_Size;
413
414
415  /*************************************************************************/
416  /*                                                                       */
417  /* <Type>                                                                */
418  /*    FT_GlyphSlot                                                       */
419  /*                                                                       */
420  /* <Description>                                                         */
421  /*    A handle to a given `glyph slot'.  A slot is a container where it  */
422  /*    is possible to load any one of the glyphs contained in its parent  */
423  /*    face.                                                              */
424  /*                                                                       */
425  /*    In other words, each time you call @FT_Load_Glyph or               */
426  /*    @FT_Load_Char, the slot's content is erased by the new glyph data, */
427  /*    i.e. the glyph's metrics, its image (bitmap or outline), and       */
428  /*    other control information.                                         */
429  /*                                                                       */
430  /* <Also>                                                                */
431  /*    @FT_GlyphSlotRec details the publicly accessible glyph fields.     */
432  /*                                                                       */
433  typedef struct FT_GlyphSlotRec_*  FT_GlyphSlot;
434
435
436  /*************************************************************************/
437  /*                                                                       */
438  /* <Type>                                                                */
439  /*    FT_CharMap                                                         */
440  /*                                                                       */
441  /* <Description>                                                         */
442  /*    A handle to a given character map.  A charmap is used to translate */
443  /*    character codes in a given encoding into glyph indexes for its     */
444  /*    parent's face.  Some font formats may provide several charmaps per */
445  /*    font.                                                              */
446  /*                                                                       */
447  /*    Each face object owns zero or more charmaps, but only one of them  */
448  /*    can be "active" and used by @FT_Get_Char_Index or @FT_Load_Char.   */
449  /*                                                                       */
450  /*    The list of available charmaps in a face is available through the  */
451  /*    "face->num_charmaps" and "face->charmaps" fields of @FT_FaceRec.   */
452  /*                                                                       */
453  /*    The currently active charmap is available as "face->charmap".      */
454  /*    You should call @FT_Set_Charmap to change it.                      */
455  /*                                                                       */
456  /* <Note>                                                                */
457  /*    When a new face is created (either through @FT_New_Face or         */
458  /*    @FT_Open_Face), the library looks for a Unicode charmap within     */
459  /*    the list and automatically activates it.                           */
460  /*                                                                       */
461  /* <Also>                                                                */
462  /*    The @FT_CharMapRec details the publicly accessible fields of a     */
463  /*    given character map.                                               */
464  /*                                                                       */
465  typedef struct FT_CharMapRec_*  FT_CharMap;
466
467
468  /*************************************************************************/
469  /*                                                                       */
470  /* <Macro>                                                               */
471  /*    FT_ENC_TAG                                                         */
472  /*                                                                       */
473  /* <Description>                                                         */
474  /*    This macro converts four letter tags into an unsigned long.  It is */
475  /*    used to define "encoding" identifiers (see @FT_Encoding).          */
476  /*                                                                       */
477  /* <Note>                                                                */
478  /*    Since many 16bit compilers don't like 32bit enumerations, you      */
479  /*    should redefine this macro in case of problems to something like   */
480  /*    this:                                                              */
481  /*                                                                       */
482  /*      #define FT_ENC_TAG( value, a, b, c, d )  value                   */
483  /*                                                                       */
484  /*    to get a simple enumeration without assigning special numbers.     */
485  /*                                                                       */
486
487#ifndef FT_ENC_TAG
488#define FT_ENC_TAG( value, a, b, c, d )         \
489          value = ( ( (FT_UInt32)(a) << 24 ) |  \
490                    ( (FT_UInt32)(b) << 16 ) |  \
491                    ( (FT_UInt32)(c) <<  8 ) |  \
492                      (FT_UInt32)(d)         )
493
494#endif /* FT_ENC_TAG */
495
496
497  /*************************************************************************/
498  /*                                                                       */
499  /* <Enum>                                                                */
500  /*    FT_Encoding                                                        */
501  /*                                                                       */
502  /* <Description>                                                         */
503  /*    An enumeration used to specify encodings supported by charmaps.    */
504  /*    Used in the @FT_Select_Charmap API function.                       */
505  /*                                                                       */
506  /* <Note>                                                                */
507  /*    Because of 32-bit charcodes defined in Unicode (i.e., surrogates), */
508  /*    all character codes must be expressed as FT_Longs.                 */
509  /*                                                                       */
510  /*    The values of this type correspond to specific character           */
511  /*    repertories (i.e. charsets), and not to text encoding methods      */
512  /*    (like UTF-8, UTF-16, GB2312_EUC, etc.).                            */
513  /*                                                                       */
514  /*    Other encodings might be defined in the future.                    */
515  /*                                                                       */
516  /* <Values>                                                              */
517  /*   FT_ENCODING_NONE ::                                                 */
518  /*     The encoding value 0 is reserved.                                 */
519  /*                                                                       */
520  /*   FT_ENCODING_UNICODE ::                                              */
521  /*     Corresponds to the Unicode character set.  This value covers      */
522  /*     all versions of the Unicode repertoire, including ASCII and       */
523  /*     Latin-1.  Most fonts include a Unicode charmap, but not all       */
524  /*     of them.                                                          */
525  /*                                                                       */
526  /*   FT_ENCODING_MS_SYMBOL ::                                            */
527  /*     Corresponds to the Microsoft Symbol encoding, used to encode      */
528  /*     mathematical symbols in the 32..255 character code range.  For    */
529  /*     more information, see `http://www.ceviz.net/symbol.htm'.          */
530  /*                                                                       */
531  /*   FT_ENCODING_SJIS ::                                                 */
532  /*     Corresponds to Japanese SJIS encoding.  More info at              */
533  /*     at `http://langsupport.japanreference.com/encoding.shtml'.        */
534  /*     See note on multi-byte encodings below.                           */
535  /*                                                                       */
536  /*   FT_ENCODING_GB2312 ::                                               */
537  /*     Corresponds to an encoding system for Simplified Chinese as used  */
538  /*     used in mainland China.                                           */
539  /*                                                                       */
540  /*   FT_ENCODING_BIG5 ::                                                 */
541  /*     Corresponds to an encoding system for Traditional Chinese as used */
542  /*     in Taiwan and Hong Kong.                                          */
543  /*                                                                       */
544  /*   FT_ENCODING_WANSUNG ::                                              */
545  /*     Corresponds to the Korean encoding system known as Wansung.       */
546  /*     For more information see                                          */
547  /*     `http://www.microsoft.com/typography/unicode/949.txt'.            */
548  /*                                                                       */
549  /*   FT_ENCODING_JOHAB ::                                                */
550  /*     The Korean standard character set (KS C-5601-1992), which         */
551  /*     corresponds to MS Windows code page 1361.  This character set     */
552  /*     includes all possible Hangeul character combinations.             */
553  /*                                                                       */
554  /*   FT_ENCODING_ADOBE_LATIN_1 ::                                        */
555  /*     Corresponds to a Latin-1 encoding as defined in a Type 1          */
556  /*     Postscript font.  It is limited to 256 character codes.           */
557  /*                                                                       */
558  /*   FT_ENCODING_ADOBE_STANDARD ::                                       */
559  /*     Corresponds to the Adobe Standard encoding, as found in Type 1,   */
560  /*     CFF, and OpenType/CFF fonts.  It is limited to 256 character      */
561  /*     codes.                                                            */
562  /*                                                                       */
563  /*   FT_ENCODING_ADOBE_EXPERT ::                                         */
564  /*     Corresponds to the Adobe Expert encoding, as found in Type 1,     */
565  /*     CFF, and OpenType/CFF fonts.  It is limited to 256 character      */
566  /*     codes.                                                            */
567  /*                                                                       */
568  /*   FT_ENCODING_ADOBE_CUSTOM ::                                         */
569  /*     Corresponds to a custom encoding, as found in Type 1, CFF, and    */
570  /*     OpenType/CFF fonts.  It is limited to 256 character codes.        */
571  /*                                                                       */
572  /*   FT_ENCODING_APPLE_ROMAN ::                                          */
573  /*     Corresponds to the 8-bit Apple roman encoding.  Many TrueType and */
574  /*     OpenType fonts contain a charmap for this encoding, since older   */
575  /*     versions of Mac OS are able to use it.                            */
576  /*                                                                       */
577  /*   FT_ENCODING_OLD_LATIN_2 ::                                          */
578  /*     This value is deprecated and was never used nor reported by       */
579  /*     FreeType.  Don't use or test for it.                              */
580  /*                                                                       */
581  /*   FT_ENCODING_MS_SJIS ::                                              */
582  /*     Same as FT_ENCODING_SJIS.  Deprecated.                            */
583  /*                                                                       */
584  /*   FT_ENCODING_MS_GB2312 ::                                            */
585  /*     Same as FT_ENCODING_GB2312.  Deprecated.                          */
586  /*                                                                       */
587  /*   FT_ENCODING_MS_BIG5 ::                                              */
588  /*     Same as FT_ENCODING_BIG5.  Deprecated.                            */
589  /*                                                                       */
590  /*   FT_ENCODING_MS_WANSUNG ::                                           */
591  /*     Same as FT_ENCODING_WANSUNG.  Deprecated.                         */
592  /*                                                                       */
593  /*   FT_ENCODING_MS_JOHAB ::                                             */
594  /*     Same as FT_ENCODING_JOHAB.  Deprecated.                           */
595  /*                                                                       */
596  /* <Note>                                                                */
597  /*   By default, FreeType automatically synthetizes a Unicode charmap    */
598  /*   for Postscript fonts, using their glyph names dictionaries.         */
599  /*   However, it will also report the encodings defined explicitly in    */
600  /*   the font file, for the cases when they are needed, with the Adobe   */
601  /*   values as well.                                                     */
602  /*                                                                       */
603  /*   FT_ENCODING_NONE is set by the BDF and PCF drivers if the charmap   */
604  /*   is neither Unicode nor ISO-8859-1 (otherwise it is set to           */
605  /*   FT_ENCODING_UNICODE).  Use `FT_Get_BDF_Charset_ID' to find out      */
606  /*   which encoding is really present.  If, for example, the             */
607  /*   `cs_registry' field is `KOI8' and the `cs_encoding' field is `R',   */
608  /*   the font is encoded in KOI8-R.                                      */
609  /*                                                                       */
610  /*   FT_ENCODING_NONE is always set (with a single exception) by the     */
611  /*   winfonts driver.  Use `FT_Get_WinFNT_Header' and examine the        */
612  /*   `charset' field of the `FT_WinFNT_HeaderRec' structure to find out  */
613  /*   which encoding is really present.  For example, FT_WinFNT_ID_CP1251 */
614  /*   (204) means Windows code page 1251 (for Russian).                   */
615  /*                                                                       */
616  /*   FT_ENCODING_NONE is set if `platform_id' is `TT_PLATFORM_MACINTOSH' */
617  /*   and `encoding_id' is not `TT_MAC_ID_ROMAN' (otherwise it is set to  */
618  /*   FT_ENCODING_APPLE_ROMAN).                                           */
619  /*                                                                       */
620  /*   If `platform_id' is `TT_PLATFORM_MACINTOSH', use the function       */
621  /*   `FT_Get_CMap_Language_ID' to query the Mac language ID which may be */
622  /*   needed to be able to distinguish Apple encoding variants.  See      */
623  /*                                                                       */
624  /*     http://www.unicode.org/Public/MAPPINGS/VENDORS/APPLE/README.TXT   */
625  /*                                                                       */
626  /*   to get an idea how to do that.  Basically, if the language ID is 0, */
627  /*   dont use it, otherwise subtract 1 from the language ID.  Then       */
628  /*   examine `encoding_id'.  If, for example, `encoding_id' is           */
629  /*   `TT_MAC_ID_ROMAN' and the language ID (minus 1) is                  */
630  /*   `TT_MAC_LANGID_GREEK', it is the Greek encoding, not Roman.         */
631  /*   `TT_MAC_ID_ARABIC' with `TT_MAC_LANGID_FARSI' means the Farsi       */
632  /*   variant the Arabic encoding.                                        */
633  /*                                                                       */
634  typedef enum  FT_Encoding_
635  {
636    FT_ENC_TAG( FT_ENCODING_NONE, 0, 0, 0, 0 ),
637
638    FT_ENC_TAG( FT_ENCODING_MS_SYMBOL,  's', 'y', 'm', 'b' ),
639    FT_ENC_TAG( FT_ENCODING_UNICODE,    'u', 'n', 'i', 'c' ),
640
641    FT_ENC_TAG( FT_ENCODING_SJIS,    's', 'j', 'i', 's' ),
642    FT_ENC_TAG( FT_ENCODING_GB2312,  'g', 'b', ' ', ' ' ),
643    FT_ENC_TAG( FT_ENCODING_BIG5,    'b', 'i', 'g', '5' ),
644    FT_ENC_TAG( FT_ENCODING_WANSUNG, 'w', 'a', 'n', 's' ),
645    FT_ENC_TAG( FT_ENCODING_JOHAB,   'j', 'o', 'h', 'a' ),
646
647    /* for backwards compatibility */
648    FT_ENCODING_MS_SJIS    = FT_ENCODING_SJIS,
649    FT_ENCODING_MS_GB2312  = FT_ENCODING_GB2312,
650    FT_ENCODING_MS_BIG5    = FT_ENCODING_BIG5,
651    FT_ENCODING_MS_WANSUNG = FT_ENCODING_WANSUNG,
652    FT_ENCODING_MS_JOHAB   = FT_ENCODING_JOHAB,
653
654    FT_ENC_TAG( FT_ENCODING_ADOBE_STANDARD, 'A', 'D', 'O', 'B' ),
655    FT_ENC_TAG( FT_ENCODING_ADOBE_EXPERT,   'A', 'D', 'B', 'E' ),
656    FT_ENC_TAG( FT_ENCODING_ADOBE_CUSTOM,   'A', 'D', 'B', 'C' ),
657    FT_ENC_TAG( FT_ENCODING_ADOBE_LATIN_1,  'l', 'a', 't', '1' ),
658
659    FT_ENC_TAG( FT_ENCODING_OLD_LATIN_2, 'l', 'a', 't', '2' ),
660
661    FT_ENC_TAG( FT_ENCODING_APPLE_ROMAN, 'a', 'r', 'm', 'n' )
662
663  } FT_Encoding;
664
665
666  /*************************************************************************/
667  /*                                                                       */
668  /* <Enum>                                                                */
669  /*    ft_encoding_xxx                                                    */
670  /*                                                                       */
671  /* <Description>                                                         */
672  /*    These constants are deprecated; use the corresponding @FT_Encoding */
673  /*    values instead.                                                    */
674  /*                                                                       */
675  /* <Values>                                                              */
676  /*   ft_encoding_none    :: see @FT_ENCODING_NONE                        */
677  /*   ft_encoding_unicode :: see @FT_ENCODING_UNICODE                     */
678  /*   ft_encoding_latin_2 :: see @FT_ENCODING_OLD_LATIN_2                 */
679  /*   ft_encoding_symbol  :: see @FT_ENCODING_MS_SYMBOL                   */
680  /*   ft_encoding_sjis    :: see @FT_ENCODING_SJIS                        */
681  /*   ft_encoding_gb2312  :: see @FT_ENCODING_GB2312                      */
682  /*   ft_encoding_big5    :: see @FT_ENCODING_BIG5                        */
683  /*   ft_encoding_wansung :: see @FT_ENCODING_WANSUNG                     */
684  /*   ft_encoding_johab   :: see @FT_ENCODING_JOHAB                       */
685  /*                                                                       */
686  /*   ft_encoding_adobe_standard :: see @FT_ENCODING_ADOBE_STANDARD       */
687  /*   ft_encoding_adobe_expert   :: see @FT_ENCODING_ADOBE_EXPERT         */
688  /*   ft_encoding_adobe_custom   :: see @FT_ENCODING_ADOBE_CUSTOM         */
689  /*   ft_encoding_latin_1        :: see @FT_ENCODING_ADOBE_LATIN_1        */
690  /*                                                                       */
691  /*   ft_encoding_apple_roman    :: see @FT_ENCODING_APPLE_ROMAN          */
692  /*                                                                       */
693#define ft_encoding_none            FT_ENCODING_NONE
694#define ft_encoding_unicode         FT_ENCODING_UNICODE
695#define ft_encoding_symbol          FT_ENCODING_MS_SYMBOL
696#define ft_encoding_latin_1         FT_ENCODING_ADOBE_LATIN_1
697#define ft_encoding_latin_2         FT_ENCODING_OLD_LATIN_2
698#define ft_encoding_sjis            FT_ENCODING_SJIS
699#define ft_encoding_gb2312          FT_ENCODING_GB2312
700#define ft_encoding_big5            FT_ENCODING_BIG5
701#define ft_encoding_wansung         FT_ENCODING_WANSUNG
702#define ft_encoding_johab           FT_ENCODING_JOHAB
703
704#define ft_encoding_adobe_standard  FT_ENCODING_ADOBE_STANDARD
705#define ft_encoding_adobe_expert    FT_ENCODING_ADOBE_EXPERT
706#define ft_encoding_adobe_custom    FT_ENCODING_ADOBE_CUSTOM
707#define ft_encoding_apple_roman     FT_ENCODING_APPLE_ROMAN
708
709
710  /*************************************************************************/
711  /*                                                                       */
712  /* <Struct>                                                              */
713  /*    FT_CharMapRec                                                      */
714  /*                                                                       */
715  /* <Description>                                                         */
716  /*    The base charmap structure.                                        */
717  /*                                                                       */
718  /* <Fields>                                                              */
719  /*    face        :: A handle to the parent face object.                 */
720  /*                                                                       */
721  /*    encoding    :: An @FT_Encoding tag identifying the charmap.  Use   */
722  /*                   this with @FT_Select_Charmap.                       */
723  /*                                                                       */
724  /*    platform_id :: An ID number describing the platform for the        */
725  /*                   following encoding ID.  This comes directly from    */
726  /*                   the TrueType specification and should be emulated   */
727  /*                   for other formats.                                  */
728  /*                                                                       */
729  /*    encoding_id :: A platform specific encoding number.  This also     */
730  /*                   comes from the TrueType specification and should be */
731  /*                   emulated similarly.                                 */
732  /*                                                                       */
733  typedef struct  FT_CharMapRec_
734  {
735    FT_Face      face;
736    FT_Encoding  encoding;
737    FT_UShort    platform_id;
738    FT_UShort    encoding_id;
739
740  } FT_CharMapRec;
741
742
743  /*************************************************************************/
744  /*************************************************************************/
745  /*                                                                       */
746  /*                 B A S E   O B J E C T   C L A S S E S                 */
747  /*                                                                       */
748  /*************************************************************************/
749  /*************************************************************************/
750
751
752  /*************************************************************************/
753  /*                                                                       */
754  /* <Type>                                                                */
755  /*    FT_Face_Internal                                                   */
756  /*                                                                       */
757  /* <Description>                                                         */
758  /*    An opaque handle to an FT_Face_InternalRec structure, used to      */
759  /*    model private data of a given @FT_Face object.                     */
760  /*                                                                       */
761  /*    This structure might change between releases of FreeType 2 and is  */
762  /*    not generally available to client applications.                    */
763  /*                                                                       */
764  typedef struct FT_Face_InternalRec_*  FT_Face_Internal;
765
766
767  /*************************************************************************/
768  /*                                                                       */
769  /* <Struct>                                                              */
770  /*    FT_FaceRec                                                         */
771  /*                                                                       */
772  /* <Description>                                                         */
773  /*    FreeType root face class structure.  A face object models the      */
774  /*    resolution and point-size independent data found in a font file.   */
775  /*                                                                       */
776  /* <Fields>                                                              */
777  /*    num_faces           :: In the case where the face is located in a  */
778  /*                           collection (i.e., a file which embeds       */
779  /*                           several faces), this is the total number of */
780  /*                           faces found in the resource.  1 by default. */
781  /*                           Accessing non-existent face indices causes  */
782  /*                           an error.                                   */
783  /*                                                                       */
784  /*    face_index          :: The index of the face in its font file.     */
785  /*                           Usually, this is 0 for all normal font      */
786  /*                           formats.  It can be > 0 in the case of      */
787  /*                           collections (which embed several fonts in a */
788  /*                           single resource/file).                      */
789  /*                                                                       */
790  /*    face_flags          :: A set of bit flags that give important      */
791  /*                           information about the face; see the         */
792  /*                           @FT_FACE_FLAG_XXX constants for details.    */
793  /*                                                                       */
794  /*    style_flags         :: A set of bit flags indicating the style of  */
795  /*                           the face (i.e., italic, bold, underline,    */
796  /*                           etc).  See the @FT_STYLE_FLAG_XXX           */
797  /*                           constants.                                  */
798  /*                                                                       */
799  /*    num_glyphs          :: The total number of glyphs in the face.     */
800  /*                                                                       */
801  /*    family_name         :: The face's family name.  This is an ASCII   */
802  /*                           string, usually in English, which describes */
803  /*                           the typeface's family (like `Times New      */
804  /*                           Roman', `Bodoni', `Garamond', etc).  This   */
805  /*                           is a least common denominator used to list  */
806  /*                           fonts.  Some formats (TrueType & OpenType)  */
807  /*                           provide localized and Unicode versions of   */
808  /*                           this string.  Applications should use the   */
809  /*                           format specific interface to access them.   */
810  /*                                                                       */
811  /*    style_name          :: The face's style name.  This is an ASCII    */
812  /*                           string, usually in English, which describes */
813  /*                           the typeface's style (like `Italic',        */
814  /*                           `Bold', `Condensed', etc).  Not all font    */
815  /*                           formats provide a style name, so this field */
816  /*                           is optional, and can be set to NULL.  As    */
817  /*                           for `family_name', some formats provide     */
818  /*                           localized/Unicode versions of this string.  */
819  /*                           Applications should use the format specific */
820  /*                           interface to access them.                   */
821  /*                                                                       */
822  /*    num_fixed_sizes     :: The number of fixed sizes available in this */
823  /*                           face.  This should be set to 0 for scalable */
824  /*                           fonts, unless its face includes a set of    */
825  /*                           glyphs (called a `strike') for the          */
826  /*                           specified sizes.                            */
827  /*                                                                       */
828  /*    available_sizes     :: An array of sizes specifying the available  */
829  /*                           bitmap/graymap sizes that are contained in  */
830  /*                           in the font face.  Should be set to NULL if */
831  /*                           the field `num_fixed_sizes' is set to 0.    */
832  /*                                                                       */
833  /*    num_charmaps        :: The total number of character maps in the   */
834  /*                           face.                                       */
835  /*                                                                       */
836  /*    charmaps            :: A table of pointers to the face's charmaps. */
837  /*                           Used to scan the list of available charmaps */
838  /*                           -- this table might change after a call to  */
839  /*                           @FT_Attach_File or @FT_Attach_Stream (e.g.  */
840  /*                           if used to hook an additional encoding or   */
841  /*                           CMap to the face object).                   */
842  /*                                                                       */
843  /*    generic             :: A field reserved for client uses.  See the  */
844  /*                           @FT_Generic type description.               */
845  /*                                                                       */
846  /*    bbox                :: The font bounding box.  Coordinates are     */
847  /*                           expressed in font units (see units_per_EM). */
848  /*                           The box is large enough to contain any      */
849  /*                           glyph from the font.  Thus, bbox.yMax can   */
850  /*                           be seen as the `maximal ascender',          */
851  /*                           bbox.yMin as the `minimal descender', and   */
852  /*                           the maximal glyph width is given by         */
853  /*                           `bbox.xMax-bbox.xMin' (not to be confused   */
854  /*                           with the maximal _advance_width_).  Only    */
855  /*                           relevant for scalable formats.              */
856  /*                                                                       */
857  /*    units_per_EM        :: The number of font units per EM square for  */
858  /*                           this face.  This is typically 2048 for      */
859  /*                           TrueType fonts, 1000 for Type1 fonts, and   */
860  /*                           should be set to the (unrealistic) value 1  */
861  /*                           for fixed-sizes fonts.  Only relevant for   */
862  /*                           scalable formats.                           */
863  /*                                                                       */
864  /*    ascender            :: The face's ascender is the vertical         */
865  /*                           distance from the baseline to the topmost   */
866  /*                           point of any glyph in the face.  This       */
867  /*                           field's value is positive, expressed in     */
868  /*                           font units.  Some font designs use a value  */
869  /*                           different from `bbox.yMax'.  Only relevant  */
870  /*                           for scalable formats.                       */
871  /*                                                                       */
872  /*    descender           :: The face's descender is the vertical        */
873  /*                           distance from the baseline to the           */
874  /*                           bottommost point of any glyph in the face.  */
875  /*                           This field's value is *negative* for values */
876  /*                           below the baseline.  It is expressed in     */
877  /*                           font units.  Some font designs use a value  */
878  /*                           different from `bbox.yMin'.  Only relevant  */
879  /*                           for scalable formats.                       */
880  /*                                                                       */
881  /*    height              :: The face's height is the vertical distance  */
882  /*                           from one baseline to the next when writing  */
883  /*                           several lines of text.  Its value is always */
884  /*                           positive, expressed in font units.  The     */
885  /*                           value can be computed as                    */
886  /*                           `ascender+descender+line_gap' where the     */
887  /*                           value of `line_gap' is also called          */
888  /*                           `external leading'.  Only relevant for      */
889  /*                           scalable formats.                           */
890  /*                                                                       */
891  /*    max_advance_width   :: The maximal advance width, in font units,   */
892  /*                           for all glyphs in this face.  This can be   */
893  /*                           used to make word wrapping computations     */
894  /*                           faster.  Only relevant for scalable         */
895  /*                           formats.                                    */
896  /*                                                                       */
897  /*    max_advance_height  :: The maximal advance height, in font units,  */
898  /*                           for all glyphs in this face.  This is only  */
899  /*                           relevant for vertical layouts, and should   */
900  /*                           be set to the `height' for fonts that do    */
901  /*                           not provide vertical metrics.  Only         */
902  /*                           relevant for scalable formats.              */
903  /*                                                                       */
904  /*    underline_position  :: The position, in font units, of the         */
905  /*                           underline line for this face.  It's the     */
906  /*                           center of the underlining stem.  Only       */
907  /*                           relevant for scalable formats.              */
908  /*                                                                       */
909  /*    underline_thickness :: The thickness, in font units, of the        */
910  /*                           underline for this face.  Only relevant for */
911  /*                           scalable formats.                           */
912  /*                                                                       */
913  /*    glyph               :: The face's associated glyph slot(s).  This  */
914  /*                           object is created automatically with a new  */
915  /*                           face object.  However, certain kinds of     */
916  /*                           applications (mainly tools like converters) */
917  /*                           can need more than one slot to ease their   */
918  /*                           task.                                       */
919  /*                                                                       */
920  /*    size                :: The current active size for this face.      */
921  /*                                                                       */
922  /*    charmap             :: The current active charmap for this face.   */
923  /*                                                                       */
924  typedef struct  FT_FaceRec_
925  {
926    FT_Long           num_faces;
927    FT_Long           face_index;
928
929    FT_Long           face_flags;
930    FT_Long           style_flags;
931
932    FT_Long           num_glyphs;
933
934    FT_String*        family_name;
935    FT_String*        style_name;
936
937    FT_Int            num_fixed_sizes;
938    FT_Bitmap_Size*   available_sizes;
939
940    FT_Int            num_charmaps;
941    FT_CharMap*       charmaps;
942
943    FT_Generic        generic;
944
945    /*# the following are only relevant to scalable outlines */
946    FT_BBox           bbox;
947
948    FT_UShort         units_per_EM;
949    FT_Short          ascender;
950    FT_Short          descender;
951    FT_Short          height;
952
953    FT_Short          max_advance_width;
954    FT_Short          max_advance_height;
955
956    FT_Short          underline_position;
957    FT_Short          underline_thickness;
958
959    FT_GlyphSlot      glyph;
960    FT_Size           size;
961    FT_CharMap        charmap;
962
963    /*@private begin */
964
965    FT_Driver         driver;
966    FT_Memory         memory;
967    FT_Stream         stream;
968
969    FT_ListRec        sizes_list;
970
971    FT_Generic        autohint;
972    void*             extensions;
973
974    FT_Face_Internal  internal;
975
976    /*@private end */
977
978  } FT_FaceRec;
979
980
981  /*************************************************************************/
982  /*                                                                       */
983  /* <Enum>                                                                */
984  /*    FT_FACE_FLAG_XXX                                                   */
985  /*                                                                       */
986  /* <Description>                                                         */
987  /*    A list of bit flags used in the `face_flags' field of the          */
988  /*    @FT_FaceRec structure.  They inform client applications of         */
989  /*    properties of the corresponding face.                              */
990  /*                                                                       */
991  /* <Values>                                                              */
992  /*    FT_FACE_FLAG_SCALABLE ::                                           */
993  /*      Indicates that the face provides vectorial outlines.  This       */
994  /*      doesn't prevent embedded bitmaps, i.e., a face can have both     */
995  /*      this bit and @FT_FACE_FLAG_FIXED_SIZES set.                      */
996  /*                                                                       */
997  /*    FT_FACE_FLAG_FIXED_SIZES ::                                        */
998  /*      Indicates that the face contains `fixed sizes', i.e., bitmap     */
999  /*      strikes for some given pixel sizes.  See the `num_fixed_sizes'   */
1000  /*      and `available_sizes' fields of @FT_FaceRec.                     */
1001  /*                                                                       */
1002  /*    FT_FACE_FLAG_FIXED_WIDTH ::                                        */
1003  /*      Indicates that the face contains fixed-width characters (like    */
1004  /*      Courier, Lucido, MonoType, etc.).                                */
1005  /*                                                                       */
1006  /*    FT_FACE_FLAG_SFNT ::                                               */
1007  /*      Indicates that the face uses the `sfnt' storage scheme.  For     */
1008  /*      now, this means TrueType and OpenType.                           */
1009  /*                                                                       */
1010  /*    FT_FACE_FLAG_HORIZONTAL ::                                         */
1011  /*      Indicates that the face contains horizontal glyph metrics.  This */
1012  /*      should be set for all common formats.                            */
1013  /*                                                                       */
1014  /*    FT_FACE_FLAG_VERTICAL ::                                           */
1015  /*      Indicates that the face contains vertical glyph metrics.  This   */
1016  /*      is only available in some formats, not all of them.              */
1017  /*                                                                       */
1018  /*    FT_FACE_FLAG_KERNING ::                                            */
1019  /*      Indicates that the face contains kerning information.  If set,   */
1020  /*      the kerning distance can be retrieved through the function       */
1021  /*      @FT_Get_Kerning.  Note that if unset, this function will always  */
1022  /*      return the vector (0,0).                                         */
1023  /*                                                                       */
1024  /*    FT_FACE_FLAG_FAST_GLYPHS ::                                        */
1025  /*      THIS FLAG IS DEPRECATED.  DO NOT USE OR TEST IT.                 */
1026  /*                                                                       */
1027  /*    FT_FACE_FLAG_MULTIPLE_MASTERS ::                                   */
1028  /*      Indicates that the font contains multiple masters and is capable */
1029  /*      of interpolating between them.  See the multiple-masters         */
1030  /*      specific API for details.                                        */
1031  /*                                                                       */
1032  /*    FT_FACE_FLAG_GLYPH_NAMES ::                                        */
1033  /*      Indicates that the font contains glyph names that can be         */
1034  /*      retrieved through @FT_Get_Glyph_Name.  Note that some TrueType   */
1035  /*      fonts contain broken glyph name tables.  Use the function        */
1036  /*      @FT_Has_PS_Glyph_Names when needed.                              */
1037  /*                                                                       */
1038  /*    FT_FACE_FLAG_EXTERNAL_STREAM ::                                    */
1039  /*      Used internally by FreeType to indicate that a face's stream was */
1040  /*      provided by the client application and should not be destroyed   */
1041  /*      when @FT_Done_Face is called.  Don't read or test this flag.     */
1042  /*                                                                       */
1043#define FT_FACE_FLAG_SCALABLE          ( 1L <<  0 )
1044#define FT_FACE_FLAG_FIXED_SIZES       ( 1L <<  1 )
1045#define FT_FACE_FLAG_FIXED_WIDTH       ( 1L <<  2 )
1046#define FT_FACE_FLAG_SFNT              ( 1L <<  3 )
1047#define FT_FACE_FLAG_HORIZONTAL        ( 1L <<  4 )
1048#define FT_FACE_FLAG_VERTICAL          ( 1L <<  5 )
1049#define FT_FACE_FLAG_KERNING           ( 1L <<  6 )
1050#define FT_FACE_FLAG_FAST_GLYPHS       ( 1L <<  7 )
1051#define FT_FACE_FLAG_MULTIPLE_MASTERS  ( 1L <<  8 )
1052#define FT_FACE_FLAG_GLYPH_NAMES       ( 1L <<  9 )
1053#define FT_FACE_FLAG_EXTERNAL_STREAM   ( 1L << 10 )
1054
1055  /* */
1056
1057
1058  /*************************************************************************/
1059  /*                                                                       */
1060  /* @macro:                                                               */
1061  /*    FT_HAS_HORIZONTAL( face )                                          */
1062  /*                                                                       */
1063  /* @description:                                                         */
1064  /*    A macro that returns true whenever a face object contains          */
1065  /*    horizontal metrics (this is true for all font formats though).     */
1066  /*                                                                       */
1067  /* @also:                                                                */
1068  /*    @FT_HAS_VERTICAL can be used to check for vertical metrics.        */
1069  /*                                                                       */
1070#define FT_HAS_HORIZONTAL( face ) \
1071          ( face->face_flags & FT_FACE_FLAG_HORIZONTAL )
1072
1073
1074  /*************************************************************************/
1075  /*                                                                       */
1076  /* @macro:                                                               */
1077  /*    FT_HAS_VERTICAL( face )                                            */
1078  /*                                                                       */
1079  /* @description:                                                         */
1080  /*    A macro that returns true whenever a face object contains vertical */
1081  /*    metrics.                                                           */
1082  /*                                                                       */
1083#define FT_HAS_VERTICAL( face ) \
1084          ( face->face_flags & FT_FACE_FLAG_VERTICAL )
1085
1086
1087  /*************************************************************************/
1088  /*                                                                       */
1089  /* @macro:                                                               */
1090  /*    FT_HAS_KERNING( face )                                             */
1091  /*                                                                       */
1092  /* @description:                                                         */
1093  /*    A macro that returns true whenever a face object contains kerning  */
1094  /*    data that can be accessed with @FT_Get_Kerning.                    */
1095  /*                                                                       */
1096#define FT_HAS_KERNING( face ) \
1097          ( face->face_flags & FT_FACE_FLAG_KERNING )
1098
1099
1100  /*************************************************************************/
1101  /*                                                                       */
1102  /* @macro:                                                               */
1103  /*    FT_IS_SCALABLE( face )                                             */
1104  /*                                                                       */
1105  /* @description:                                                         */
1106  /*    A macro that returns true whenever a face object contains a        */
1107  /*    scalable font face (true for TrueType, Type 1, CID, and            */
1108  /*    OpenType/CFF font formats.                                         */
1109  /*                                                                       */
1110#define FT_IS_SCALABLE( face ) \
1111          ( face->face_flags & FT_FACE_FLAG_SCALABLE )
1112
1113
1114  /*************************************************************************/
1115  /*                                                                       */
1116  /* @macro:                                                               */
1117  /*    FT_IS_SFNT( face )                                                 */
1118  /*                                                                       */
1119  /* @description:                                                         */
1120  /*    A macro that returns true whenever a face object contains a font   */
1121  /*    whose format is based on the SFNT storage scheme.  This usually    */
1122  /*    means: TrueType fonts, OpenType fonts, as well as SFNT-based       */
1123  /*    embedded bitmap fonts.                                             */
1124  /*                                                                       */
1125  /*    If this macro is true, all functions defined in @FT_SFNT_NAMES_H   */
1126  /*    and @FT_TRUETYPE_TABLES_H are available.                           */
1127  /*                                                                       */
1128#define FT_IS_SFNT( face ) \
1129          ( face->face_flags & FT_FACE_FLAG_SFNT )
1130
1131
1132  /*************************************************************************/
1133  /*                                                                       */
1134  /* @macro:                                                               */
1135  /*    FT_IS_FIXED_WIDTH( face )                                          */
1136  /*                                                                       */
1137  /* @description:                                                         */
1138  /*    A macro that returns true whenever a face object contains a font   */
1139  /*    face that contains fixed-width (or "monospace", "fixed-pitch",     */
1140  /*    etc.) glyphs.                                                      */
1141  /*                                                                       */
1142#define FT_IS_FIXED_WIDTH( face ) \
1143          ( face->face_flags & FT_FACE_FLAG_FIXED_WIDTH )
1144
1145
1146  /*************************************************************************/
1147  /*                                                                       */
1148  /* @macro:                                                               */
1149  /*    FT_HAS_FIXED_SIZES( face )                                         */
1150  /*                                                                       */
1151  /* @description:                                                         */
1152  /*    A macro that returns true whenever a face object contains some     */
1153  /*    embedded bitmaps.  See the `available_sizes' field of the          */
1154  /*    @FT_FaceRec structure.                                             */
1155  /*                                                                       */
1156#define FT_HAS_FIXED_SIZES( face ) \
1157          ( face->face_flags & FT_FACE_FLAG_FIXED_SIZES )
1158
1159
1160   /* */
1161
1162
1163  /*************************************************************************/
1164  /*                                                                       */
1165  /* @macro:                                                               */
1166  /*    FT_HAS_FAST_GLYPHS( face )                                         */
1167  /*                                                                       */
1168  /* @description:                                                         */
1169  /*    Deprecated; indicates that the face contains so-called "fast"      */
1170  /*    glyph bitmaps.                                                     */
1171  /*                                                                       */
1172#define FT_HAS_FAST_GLYPHS( face ) \
1173          ( face->face_flags & FT_FACE_FLAG_FAST_GLYPHS )
1174
1175
1176  /*************************************************************************/
1177  /*                                                                       */
1178  /* @macro:                                                               */
1179  /*    FT_HAS_GLYPH_NAMES( face )                                         */
1180  /*                                                                       */
1181  /* @description:                                                         */
1182  /*    A macro that returns true whenever a face object contains some     */
1183  /*    glyph names that can be accessed through @FT_Get_Glyph_Name.       */
1184  /*                                                                       */
1185#define FT_HAS_GLYPH_NAMES( face ) \
1186          ( face->face_flags & FT_FACE_FLAG_GLYPH_NAMES )
1187
1188
1189  /*************************************************************************/
1190  /*                                                                       */
1191  /* @macro:                                                               */
1192  /*    FT_HAS_MULTIPLE_MASTERS( face )                                    */
1193  /*                                                                       */
1194  /* @description:                                                         */
1195  /*    A macro that returns true whenever a face object contains some     */
1196  /*    multiple masters.  The functions provided by                       */
1197  /*    @FT_MULTIPLE_MASTERS_H are then available to choose the exact      */
1198  /*    design you want.                                                   */
1199  /*                                                                       */
1200#define FT_HAS_MULTIPLE_MASTERS( face ) \
1201          ( face->face_flags & FT_FACE_FLAG_MULTIPLE_MASTERS )
1202
1203
1204  /*************************************************************************/
1205  /*                                                                       */
1206  /* <Constant>                                                            */
1207  /*    FT_STYLE_FLAG_XXX                                                  */
1208  /*                                                                       */
1209  /* <Description>                                                         */
1210  /*    A list of bit-flags used to indicate the style of a given face.    */
1211  /*    These are used in the `style_flags' field of @FT_FaceRec.          */
1212  /*                                                                       */
1213  /* <Values>                                                              */
1214  /*    FT_STYLE_FLAG_ITALIC ::                                            */
1215  /*      Indicates that a given face is italicized.                       */
1216  /*                                                                       */
1217  /*    FT_STYLE_FLAG_BOLD ::                                              */
1218  /*      Indicates that a given face is bold.                             */
1219  /*                                                                       */
1220#define FT_STYLE_FLAG_ITALIC  ( 1 << 0 )
1221#define FT_STYLE_FLAG_BOLD    ( 1 << 1 )
1222
1223
1224  /*************************************************************************/
1225  /*                                                                       */
1226  /* <Type>                                                                */
1227  /*    FT_Size_Internal                                                   */
1228  /*                                                                       */
1229  /* <Description>                                                         */
1230  /*    An opaque handle to an FT_Size_InternalRec structure, used to      */
1231  /*    model private data of a given FT_Size object.                      */
1232  /*                                                                       */
1233  typedef struct FT_Size_InternalRec_*  FT_Size_Internal;
1234
1235
1236  /*************************************************************************/
1237  /*                                                                       */
1238  /* <Struct>                                                              */
1239  /*    FT_Size_Metrics                                                    */
1240  /*                                                                       */
1241  /* <Description>                                                         */
1242  /*    The size metrics structure returned scaled important distances for */
1243  /*    a given size object.                                               */
1244  /*                                                                       */
1245  /* <Fields>                                                              */
1246  /*    x_ppem       :: The character width, expressed in integer pixels.  */
1247  /*                    This is the width of the EM square expressed in    */
1248  /*                    pixels, hence the term `ppem' (pixels per EM).     */
1249  /*                                                                       */
1250  /*    y_ppem       :: The character height, expressed in integer pixels. */
1251  /*                    This is the height of the EM square expressed in   */
1252  /*                    pixels, hence the term `ppem' (pixels per EM).     */
1253  /*                                                                       */
1254  /*    x_scale      :: A simple 16.16 fixed point format coefficient used */
1255  /*                    to scale horizontal distances expressed in font    */
1256  /*                    units to fractional (26.6) pixel coordinates.      */
1257  /*                                                                       */
1258  /*    y_scale      :: A simple 16.16 fixed point format coefficient used */
1259  /*                    to scale vertical distances expressed in font      */
1260  /*                    units to fractional (26.6) pixel coordinates.      */
1261  /*                                                                       */
1262  /*    ascender     :: The ascender, expressed in 26.6 fixed point        */
1263  /*                    pixels.  Positive for ascenders above the          */
1264  /*                    baseline.                                          */
1265  /*                                                                       */
1266  /*    descender    :: The descender, expressed in 26.6 fixed point       */
1267  /*                    pixels.  Negative for descenders below the         */
1268  /*                    baseline.                                          */
1269  /*                                                                       */
1270  /*    height       :: The text height, expressed in 26.6 fixed point     */
1271  /*                    pixels.  Always positive.                          */
1272  /*                                                                       */
1273  /*    max_advance  :: Maximum horizontal advance, expressed in 26.6      */
1274  /*                    fixed point pixels.  Always positive.              */
1275  /*                                                                       */
1276  /* <Note>                                                                */
1277  /*    For scalable fonts, the values of `ascender', `descender', and     */
1278  /*    `height' are scaled versions of `face->ascender',                  */
1279  /*    `face->descender', and `face->height', respectively.               */
1280  /*                                                                       */
1281  /*    Unfortunately, due to glyph hinting, these values might not be     */
1282  /*    exact for certain fonts.  They thus must be treated as unreliable  */
1283  /*    with an error margin of at least one pixel!                        */
1284  /*                                                                       */
1285  /*    Indeed, the only way to get the exact pixel ascender and descender */
1286  /*    is to render _all_ glyphs.  As this would be a definite            */
1287  /*    performance hit, it is up to client applications to perform such   */
1288  /*    computations.                                                      */
1289  /*                                                                       */
1290  typedef struct  FT_Size_Metrics_
1291  {
1292    FT_UShort  x_ppem;      /* horizontal pixels per EM               */
1293    FT_UShort  y_ppem;      /* vertical pixels per EM                 */
1294
1295    FT_Fixed   x_scale;     /* two scales used to convert font units  */
1296    FT_Fixed   y_scale;     /* to 26.6 frac. pixel coordinates        */
1297
1298    FT_Pos     ascender;    /* ascender in 26.6 frac. pixels          */
1299    FT_Pos     descender;   /* descender in 26.6 frac. pixels         */
1300    FT_Pos     height;      /* text height in 26.6 frac. pixels       */
1301    FT_Pos     max_advance; /* max horizontal advance, in 26.6 pixels */
1302
1303  } FT_Size_Metrics;
1304
1305
1306  /*************************************************************************/
1307  /*                                                                       */
1308  /* <Struct>                                                              */
1309  /*    FT_SizeRec                                                         */
1310  /*                                                                       */
1311  /* <Description>                                                         */
1312  /*    FreeType root size class structure.  A size object models the      */
1313  /*    resolution and pointsize dependent data of a given face.           */
1314  /*                                                                       */
1315  /* <Fields>                                                              */
1316  /*    face    :: Handle to the parent face object.                       */
1317  /*                                                                       */
1318  /*    generic :: A typeless pointer, which is unused by the FreeType     */
1319  /*               library or any of its drivers.  It can be used by       */
1320  /*               client applications to link their own data to each size */
1321  /*               object.                                                 */
1322  /*                                                                       */
1323  /*    metrics :: Metrics for this size object.  This field is read-only. */
1324  /*                                                                       */
1325  typedef struct  FT_SizeRec_
1326  {
1327    FT_Face           face;      /* parent face object              */
1328    FT_Generic        generic;   /* generic pointer for client uses */
1329    FT_Size_Metrics   metrics;   /* size metrics                    */
1330    FT_Size_Internal  internal;
1331
1332  } FT_SizeRec;
1333
1334
1335  /*************************************************************************/
1336  /*                                                                       */
1337  /* <Struct>                                                              */
1338  /*    FT_SubGlyph                                                        */
1339  /*                                                                       */
1340  /* <Description>                                                         */
1341  /*    The subglyph structure is an internal object used to describe      */
1342  /*    subglyphs (for example, in the case of composites).                */
1343  /*                                                                       */
1344  /* <Note>                                                                */
1345  /*    The subglyph implementation is not part of the high-level API,     */
1346  /*    hence the forward structure declaration.                           */
1347  /*                                                                       */
1348  typedef struct FT_SubGlyphRec_*  FT_SubGlyph;
1349
1350
1351  /*************************************************************************/
1352  /*                                                                       */
1353  /* <Type>                                                                */
1354  /*    FT_Slot_Internal                                                   */
1355  /*                                                                       */
1356  /* <Description>                                                         */
1357  /*    An opaque handle to an FT_Slot_InternalRec structure, used to      */
1358  /*    model private data of a given FT_GlyphSlot object.                 */
1359  /*                                                                       */
1360  typedef struct FT_Slot_InternalRec_*  FT_Slot_Internal;
1361
1362
1363  /*************************************************************************/
1364  /*                                                                       */
1365  /* <Struct>                                                              */
1366  /*    FT_GlyphSlotRec                                                    */
1367  /*                                                                       */
1368  /* <Description>                                                         */
1369  /*    FreeType root glyph slot class structure.  A glyph slot is a       */
1370  /*    container where individual glyphs can be loaded, be they           */
1371  /*    vectorial or bitmap/graymaps.                                      */
1372  /*                                                                       */
1373  /* <Fields>                                                              */
1374  /*    library           :: A handle to the FreeType library instance     */
1375  /*                         this slot belongs to.                         */
1376  /*                                                                       */
1377  /*    face              :: A handle to the parent face object.           */
1378  /*                                                                       */
1379  /*    next              :: In some cases (like some font tools), several */
1380  /*                         glyph slots per face object can be a good     */
1381  /*                         thing.  As this is rare, the glyph slots are  */
1382  /*                         listed through a direct, single-linked list   */
1383  /*                         using its `next' field.                       */
1384  /*                                                                       */
1385  /*    generic           :: A typeless pointer which is unused by the     */
1386  /*                         FreeType library or any of its drivers.  It   */
1387  /*                         can be used by client applications to link    */
1388  /*                         their own data to each glyph slot object.     */
1389  /*                                                                       */
1390  /*    metrics           :: The metrics of the last loaded glyph in the   */
1391  /*                         slot.  The returned values depend on the last */
1392  /*                         load flags (see the @FT_Load_Glyph API        */
1393  /*                         function) and can be expressed either in 26.6 */
1394  /*                         fractional pixels or font units.              */
1395  /*                                                                       */
1396  /*                         Note that even when the glyph image is        */
1397  /*                         transformed, the metrics are not.             */
1398  /*                                                                       */
1399  /*    linearHoriAdvance :: For scalable formats only, this field holds   */
1400  /*                         the linearly scaled horizontal advance width  */
1401  /*                         for the glyph (i.e. the scaled and unhinted   */
1402  /*                         value of the hori advance).  This can be      */
1403  /*                         important to perform correct WYSIWYG layout.  */
1404  /*                                                                       */
1405  /*                         Note that this value is expressed by default  */
1406  /*                         in 16.16 pixels. However, when the glyph is   */
1407  /*                         loaded with the FT_LOAD_LINEAR_DESIGN flag,   */
1408  /*                         this field contains simply the value of the   */
1409  /*                         advance in original font units.               */
1410  /*                                                                       */
1411  /*    linearVertAdvance :: For scalable formats only, this field holds   */
1412  /*                         the linearly scaled vertical advance height   */
1413  /*                         for the glyph.  See linearHoriAdvance for     */
1414  /*                         comments.                                     */
1415  /*                                                                       */
1416  /*    advance           :: This is the transformed advance width for the */
1417  /*                         glyph.                                        */
1418  /*                                                                       */
1419  /*    format            :: This field indicates the format of the image  */
1420  /*                         contained in the glyph slot.  Typically       */
1421  /*                         FT_GLYPH_FORMAT_BITMAP,                       */
1422  /*                         FT_GLYPH_FORMAT_OUTLINE, and                  */
1423  /*                         FT_GLYPH_FORMAT_COMPOSITE, but others are     */
1424  /*                         possible.                                     */
1425  /*                                                                       */
1426  /*    bitmap            :: This field is used as a bitmap descriptor     */
1427  /*                         when the slot format is                       */
1428  /*                         FT_GLYPH_FORMAT_BITMAP.  Note that the        */
1429  /*                         address and content of the bitmap buffer can  */
1430  /*                         change between calls of @FT_Load_Glyph and a  */
1431  /*                         few other functions.                          */
1432  /*                                                                       */
1433  /*    bitmap_left       :: This is the bitmap's left bearing expressed   */
1434  /*                         in integer pixels.  Of course, this is only   */
1435  /*                         valid if the format is                        */
1436  /*                         FT_GLYPH_FORMAT_BITMAP.                       */
1437  /*                                                                       */
1438  /*    bitmap_top        :: This is the bitmap's top bearing expressed in */
1439  /*                         integer pixels.  Remember that this is the    */
1440  /*                         distance from the baseline to the top-most    */
1441  /*                         glyph scanline, upwards y-coordinates being   */
1442  /*                         *positive*.                                   */
1443  /*                                                                       */
1444  /*    outline           :: The outline descriptor for the current glyph  */
1445  /*                         image if its format is                        */
1446  /*                         FT_GLYPH_FORMAT_OUTLINE.                      */
1447  /*                                                                       */
1448  /*    num_subglyphs     :: The number of subglyphs in a composite glyph. */
1449  /*                         This field is only valid for the composite    */
1450  /*                         glyph format that should normally only be     */
1451  /*                         loaded with the @FT_LOAD_NO_RECURSE flag.     */
1452  /*                         For now this is internal to FreeType.         */
1453  /*                                                                       */
1454  /*    subglyphs         :: An array of subglyph descriptors for          */
1455  /*                         composite glyphs.  There are `num_subglyphs'  */
1456  /*                         elements in there.  Currently internal to     */
1457  /*                         FreeType.                                     */
1458  /*                                                                       */
1459  /*    control_data      :: Certain font drivers can also return the      */
1460  /*                         control data for a given glyph image (e.g.    */
1461  /*                         TrueType bytecode, Type 1 charstrings, etc.). */
1462  /*                         This field is a pointer to such data.         */
1463  /*                                                                       */
1464  /*    control_len       :: This is the length in bytes of the control    */
1465  /*                         data.                                         */
1466  /*                                                                       */
1467  /*    other             :: Really wicked formats can use this pointer to */
1468  /*                         present their own glyph image to client apps. */
1469  /*                         Note that the app will need to know about the */
1470  /*                         image format.                                 */
1471  /*                                                                       */
1472  /*    lsb_delta         :: The difference between hinted and unhinted    */
1473  /*                         left side bearing while autohinting is        */
1474  /*                         active.  Zero otherwise.                      */
1475  /*                                                                       */
1476  /*    rsb_delta         :: The difference between hinted and unhinted    */
1477  /*                         right side bearing while autohinting is       */
1478  /*                         active.  Zero otherwise.                      */
1479  /*                                                                       */
1480  /* <Note>                                                                */
1481  /*    If @FT_Load_Glyph is called with default flags (see                */
1482  /*    @FT_LOAD_DEFAULT) the glyph image is loaded in the glyph slot in   */
1483  /*    its native format (e.g. a vectorial outline for TrueType and       */
1484  /*    Type 1 formats).                                                   */
1485  /*                                                                       */
1486  /*    This image can later be converted into a bitmap by calling         */
1487  /*    @FT_Render_Glyph.  This function finds the current renderer for    */
1488  /*    the native image's format then invokes it.                         */
1489  /*                                                                       */
1490  /*    The renderer is in charge of transforming the native image through */
1491  /*    the slot's face transformation fields, then convert it into a      */
1492  /*    bitmap that is returned in `slot->bitmap'.                         */
1493  /*                                                                       */
1494  /*    Note that `slot->bitmap_left' and `slot->bitmap_top' are also used */
1495  /*    to specify the position of the bitmap relative to the current pen  */
1496  /*    position (e.g. coordinates [0,0] on the baseline).  Of course,     */
1497  /*    `slot->format' is also changed to `FT_GLYPH_FORMAT_BITMAP' .       */
1498  /*                                                                       */
1499  /* <Note>                                                                */
1500  /*    Here a small pseudo code fragment which shows how to use           */
1501  /*    `lsb_delta' and `rsb_delta':                                       */
1502  /*                                                                       */
1503  /*    {                                                                  */
1504  /*      FT_Pos  origin_x       = 0;                                      */
1505  /*      FT_Pos  prev_rsb_delta = 0;                                      */
1506  /*                                                                       */
1507  /*                                                                       */
1508  /*      for all glyphs do                                                */
1509  /*        <compute kern between current and previous glyph and add it to */
1510  /*         `origin_x'>                                                   */
1511  /*                                                                       */
1512  /*        <load glyph with `FT_Load_Glyph'>                              */
1513  /*                                                                       */
1514  /*        if ( prev_rsb_delta - face->glyph->lsb_delta >= 32 )           */
1515  /*          origin_x -= 64;                                              */
1516  /*        else if ( prev_rsb_delta - face->glyph->lsb_delta < -32 )      */
1517  /*          origin_x += 64;                                              */
1518  /*                                                                       */
1519  /*        prev_rsb_delta = face->glyph->rsb_delta;                       */
1520  /*                                                                       */
1521  /*        <save glyph image, or render glyph, or ...>                    */
1522  /*                                                                       */
1523  /*        origin_x += face->glyph->advance.x;                            */
1524  /*      endfor                                                           */
1525  /*    }                                                                  */
1526  /*                                                                       */
1527  typedef struct  FT_GlyphSlotRec_
1528  {
1529    FT_Library        library;
1530    FT_Face           face;
1531    FT_GlyphSlot      next;
1532    FT_UInt           reserved;       /* retained for binary compatibility */
1533    FT_Generic        generic;
1534
1535    FT_Glyph_Metrics  metrics;
1536    FT_Fixed          linearHoriAdvance;
1537    FT_Fixed          linearVertAdvance;
1538    FT_Vector         advance;
1539
1540    FT_Glyph_Format   format;
1541
1542    FT_Bitmap         bitmap;
1543    FT_Int            bitmap_left;
1544    FT_Int            bitmap_top;
1545
1546    FT_Outline        outline;
1547
1548    FT_UInt           num_subglyphs;
1549    FT_SubGlyph       subglyphs;
1550
1551    void*             control_data;
1552    long              control_len;
1553
1554    FT_Pos            lsb_delta;
1555    FT_Pos            rsb_delta;
1556
1557    void*             other;
1558
1559    FT_Slot_Internal  internal;
1560
1561  } FT_GlyphSlotRec;
1562
1563
1564  /*************************************************************************/
1565  /*************************************************************************/
1566  /*                                                                       */
1567  /*                         F U N C T I O N S                             */
1568  /*                                                                       */
1569  /*************************************************************************/
1570  /*************************************************************************/
1571
1572
1573  /*************************************************************************/
1574  /*                                                                       */
1575  /* <Function>                                                            */
1576  /*    FT_Init_FreeType                                                   */
1577  /*                                                                       */
1578  /* <Description>                                                         */
1579  /*    Initializes a new FreeType library object.  The set of modules     */
1580  /*    that are registered by this function is determined at build time.  */
1581  /*                                                                       */
1582  /* <Output>                                                              */
1583  /*    alibrary :: A handle to a new library object.                      */
1584  /*                                                                       */
1585  /* <Return>                                                              */
1586  /*    FreeType error code.  0 means success.                             */
1587  /*                                                                       */
1588  FT_EXPORT( FT_Error )
1589  FT_Init_FreeType( FT_Library  *alibrary );
1590
1591
1592  /*************************************************************************/
1593  /*                                                                       */
1594  /* <Function>                                                            */
1595  /*    FT_Library_Version                                                 */
1596  /*                                                                       */
1597  /* <Description>                                                         */
1598  /*    Return the version of the FreeType library being used.  This is    */
1599  /*    useful when dynamically linking to the library, since one cannot   */
1600  /*    use the macros FT_FREETYPE_MAJOR, FT_FREETYPE_MINOR, and           */
1601  /*    FT_FREETYPE_PATCH.                                                 */
1602  /*                                                                       */
1603  /* <Input>                                                               */
1604  /*    library :: A source library handle.                                */
1605  /*                                                                       */
1606  /* <Output>                                                              */
1607  /*    amajor :: The major version number.                                */
1608  /*                                                                       */
1609  /*    aminor :: The minor version number.                                */
1610  /*                                                                       */
1611  /*    apatch :: The patch version number.                                */
1612  /*                                                                       */
1613  /* <Note>                                                                */
1614  /*    The reason why this function takes a 'library' argument is because */
1615  /*    certain programs implement library initialization in a custom way  */
1616  /*    that doesn't use `FT_Init_FreeType'.                               */
1617  /*                                                                       */
1618  /*    In such cases, the library version might not be available before   */
1619  /*    the library object has been created.                               */
1620  /*                                                                       */
1621  FT_EXPORT( void )
1622  FT_Library_Version( FT_Library   library,
1623                      FT_Int      *amajor,
1624                      FT_Int      *aminor,
1625                      FT_Int      *apatch );
1626
1627
1628  /*************************************************************************/
1629  /*                                                                       */
1630  /* <Function>                                                            */
1631  /*    FT_Done_FreeType                                                   */
1632  /*                                                                       */
1633  /* <Description>                                                         */
1634  /*    Destroys a given FreeType library object and all of its childs,    */
1635  /*    including resources, drivers, faces, sizes, etc.                   */
1636  /*                                                                       */
1637  /* <Input>                                                               */
1638  /*    library :: A handle to the target library object.                  */
1639  /*                                                                       */
1640  /* <Return>                                                              */
1641  /*    FreeType error code.  0 means success.                             */
1642  /*                                                                       */
1643  FT_EXPORT( FT_Error )
1644  FT_Done_FreeType( FT_Library  library );
1645
1646
1647  /*************************************************************************/
1648  /*                                                                       */
1649  /* <Enum>                                                                */
1650  /*    FT_OPEN_XXX                                                        */
1651  /*                                                                       */
1652  /* <Description>                                                         */
1653  /*    A list of bit-field constants used within the `flags' field of the */
1654  /*    @FT_Open_Args structure.                                           */
1655  /*                                                                       */
1656  /* <Values>                                                              */
1657  /*    FT_OPEN_MEMORY      :: This is a memory-based stream.              */
1658  /*                                                                       */
1659  /*    FT_OPEN_STREAM      :: Copy the stream from the `stream' field.    */
1660  /*                                                                       */
1661  /*    FT_OPEN_PATHNAME    :: Create a new input stream from a C          */
1662  /*                           path name.                                  */
1663  /*                                                                       */
1664  /*    FT_OPEN_DRIVER      :: Use the `driver' field.                     */
1665  /*                                                                       */
1666  /*    FT_OPEN_PARAMS      :: Use the `num_params' & `params' field.      */
1667  /*                                                                       */
1668  /*    ft_open_memory      :: Deprecated; use @FT_OPEN_MEMORY instead.    */
1669  /*                                                                       */
1670  /*    ft_open_stream      :: Deprecated; use @FT_OPEN_STREAM instead.    */
1671  /*                                                                       */
1672  /*    ft_open_pathname    :: Deprecated; use @FT_OPEN_PATHNAME instead.  */
1673  /*                                                                       */
1674  /*    ft_open_driver      :: Deprecated; use @FT_OPEN_DRIVER instead.    */
1675  /*                                                                       */
1676  /*    ft_open_params      :: Deprecated; use @FT_OPEN_PARAMS instead.    */
1677  /*                                                                       */
1678  /* <Note>                                                                */
1679  /*    The `FT_OPEN_MEMORY', `FT_OPEN_STREAM', and `FT_OPEN_PATHNAME'     */
1680  /*    flags are mutually exclusive.                                      */
1681  /*                                                                       */
1682#define FT_OPEN_MEMORY    0x1
1683#define FT_OPEN_STREAM    0x2
1684#define FT_OPEN_PATHNAME  0x4
1685#define FT_OPEN_DRIVER    0x8
1686#define FT_OPEN_PARAMS    0x10
1687
1688#define ft_open_memory    FT_OPEN_MEMORY     /* deprecated */
1689#define ft_open_stream    FT_OPEN_STREAM     /* deprecated */
1690#define ft_open_pathname  FT_OPEN_PATHNAME   /* deprecated */
1691#define ft_open_driver    FT_OPEN_DRIVER     /* deprecated */
1692#define ft_open_params    FT_OPEN_PARAMS     /* deprecated */
1693
1694
1695  /*************************************************************************/
1696  /*                                                                       */
1697  /* <Struct>                                                              */
1698  /*    FT_Parameter                                                       */
1699  /*                                                                       */
1700  /* <Description>                                                         */
1701  /*    A simple structure used to pass more or less generic parameters    */
1702  /*    to @FT_Open_Face.                                                  */
1703  /*                                                                       */
1704  /* <Fields>                                                              */
1705  /*    tag  :: A 4-byte identification tag.                               */
1706  /*                                                                       */
1707  /*    data :: A pointer to the parameter data.                           */
1708  /*                                                                       */
1709  /* <Note>                                                                */
1710  /*    The id and function of parameters are driver-specific.             */
1711  /*                                                                       */
1712  typedef struct  FT_Parameter_
1713  {
1714    FT_ULong    tag;
1715    FT_Pointer  data;
1716
1717  } FT_Parameter;
1718
1719
1720  /*************************************************************************/
1721  /*                                                                       */
1722  /* <Struct>                                                              */
1723  /*    FT_Open_Args                                                       */
1724  /*                                                                       */
1725  /* <Description>                                                         */
1726  /*    A structure used to indicate how to open a new font file/stream.   */
1727  /*    A pointer to such a structure can be used as a parameter for the   */
1728  /*    functions @FT_Open_Face and @FT_Attach_Stream.                     */
1729  /*                                                                       */
1730  /* <Fields>                                                              */
1731  /*    flags       :: A set of bit flags indicating how to use the        */
1732  /*                   structure.                                          */
1733  /*                                                                       */
1734  /*    memory_base :: The first byte of the file in memory.               */
1735  /*                                                                       */
1736  /*    memory_size :: The size in bytes of the file in memory.            */
1737  /*                                                                       */
1738  /*    pathname    :: A pointer to an 8-bit file pathname.                */
1739  /*                                                                       */
1740  /*    stream      :: A handle to a source stream object.                 */
1741  /*                                                                       */
1742  /*    driver      :: This field is exclusively used by @FT_Open_Face;    */
1743  /*                   it simply specifies the font driver to use to open  */
1744  /*                   the face.  If set to 0, FreeType will try to load   */
1745  /*                   the face with each one of the drivers in its list.  */
1746  /*                                                                       */
1747  /*    num_params  :: The number of extra parameters.                     */
1748  /*                                                                       */
1749  /*    params      :: Extra parameters passed to the font driver when     */
1750  /*                   opening a new face.                                 */
1751  /*                                                                       */
1752  /* <Note>                                                                */
1753  /*    The stream type is determined by the contents of `flags' which     */
1754  /*    are tested in the following order by @FT_Open_Face:                */
1755  /*                                                                       */
1756  /*    If the `FT_OPEN_MEMORY' bit is set, assume that this is a          */
1757  /*    memory file of `memory_size' bytes,located at `memory_address'.    */
1758  /*                                                                       */
1759  /*    Otherwise, if the `FT_OPEN_STREAM' bit is set, assume that a       */
1760  /*    custom input stream `stream' is used.                              */
1761  /*                                                                       */
1762  /*    Otherwise, if the `FT_OPEN_PATHNAME' bit is set, assume that this  */
1763  /*    is a normal file and use `pathname' to open it.                    */
1764  /*                                                                       */
1765  /*    If the `FT_OPEN_DRIVER' bit is set, @FT_Open_Face will only try to */
1766  /*    open the file with the driver whose handler is in `driver'.        */
1767  /*                                                                       */
1768  /*    If the `FT_OPEN_PARAMS' bit is set, the parameters given by        */
1769  /*    `num_params' and `params' will be used.  They are ignored          */
1770  /*    otherwise.                                                         */
1771  /*                                                                       */
1772  typedef struct  FT_Open_Args_
1773  {
1774    FT_UInt         flags;
1775    const FT_Byte*  memory_base;
1776    FT_Long         memory_size;
1777    FT_String*      pathname;
1778    FT_Stream       stream;
1779    FT_Module       driver;
1780    FT_Int          num_params;
1781    FT_Parameter*   params;
1782
1783  } FT_Open_Args;
1784
1785
1786  /*************************************************************************/
1787  /*                                                                       */
1788  /* <Function>                                                            */
1789  /*    FT_New_Face                                                        */
1790  /*                                                                       */
1791  /* <Description>                                                         */
1792  /*    Creates a new face object from a given resource and typeface index */
1793  /*    using a pathname to the font file.                                 */
1794  /*                                                                       */
1795  /* <InOut>                                                               */
1796  /*    library    :: A handle to the library resource.                    */
1797  /*                                                                       */
1798  /* <Input>                                                               */
1799  /*    pathname   :: A path to the font file.                             */
1800  /*                                                                       */
1801  /*    face_index :: The index of the face within the resource.  The      */
1802  /*                  first face has index 0.                              */
1803  /*                                                                       */
1804  /* <Output>                                                              */
1805  /*    aface      :: A handle to a new face object.                       */
1806  /*                                                                       */
1807  /* <Return>                                                              */
1808  /*    FreeType error code.  0 means success.                             */
1809  /*                                                                       */
1810  /* <Note>                                                                */
1811  /*    Unlike FreeType 1.x, this function automatically creates a glyph   */
1812  /*    slot for the face object which can be accessed directly through    */
1813  /*    `face->glyph'.                                                     */
1814  /*                                                                       */
1815  /*    @FT_New_Face can be used to determine and/or check the font format */
1816  /*    of a given font resource.  If the `face_index' field is negative,  */
1817  /*    the function will _not_ return any face handle in `aface';  the    */
1818  /*    return value is 0 if the font format is recognized, or non-zero    */
1819  /*    otherwise.                                                         */
1820  /*                                                                       */
1821  /*    Each new face object created with this function also owns a        */
1822  /*    default @FT_Size object, accessible as `face->size'.               */
1823  /*                                                                       */
1824  FT_EXPORT( FT_Error )
1825  FT_New_Face( FT_Library   library,
1826               const char*  filepathname,
1827               FT_Long      face_index,
1828               FT_Face     *aface );
1829
1830
1831  /*************************************************************************/
1832  /*                                                                       */
1833  /* <Function>                                                            */
1834  /*    FT_New_Memory_Face                                                 */
1835  /*                                                                       */
1836  /* <Description>                                                         */
1837  /*    Creates a new face object from a given resource and typeface index */
1838  /*    using a font file already loaded into memory.                      */
1839  /*                                                                       */
1840  /* <InOut>                                                               */
1841  /*    library    :: A handle to the library resource.                    */
1842  /*                                                                       */
1843  /* <Input>                                                               */
1844  /*    file_base  :: A pointer to the beginning of the font data.         */
1845  /*                                                                       */
1846  /*    file_size  :: The size of the memory chunk used by the font data.  */
1847  /*                                                                       */
1848  /*    face_index :: The index of the face within the resource.  The      */
1849  /*                  first face has index 0.                              */
1850  /*                                                                       */
1851  /* <Output>                                                              */
1852  /*    aface      :: A handle to a new face object.                       */
1853  /*                                                                       */
1854  /* <Return>                                                              */
1855  /*    FreeType error code.  0 means success.                             */
1856  /*                                                                       */
1857  /* <Note>                                                                */
1858  /*    The font data bytes are used _directly_ by the @FT_Face object.    */
1859  /*    This means that they are not copied, and that the client is        */
1860  /*    responsible for releasing/destroying them _after_ the              */
1861  /*    corresponding call to @FT_Done_Face .                              */
1862  /*                                                                       */
1863  /*    Unlike FreeType 1.x, this function automatically creates a glyph   */
1864  /*    slot for the face object which can be accessed directly through    */
1865  /*    `face->glyph'.                                                     */
1866  /*                                                                       */
1867  /*    @FT_New_Memory_Face can be used to determine and/or check the font */
1868  /*    format of a given font resource.  If the `face_index' field is     */
1869  /*    negative, the function will _not_ return any face handle in        */
1870  /*    `aface'; the return value is 0 if the font format is recognized,   */
1871  /*    or non-zero otherwise.                                             */
1872  /*                                                                       */
1873  FT_EXPORT( FT_Error )
1874  FT_New_Memory_Face( FT_Library      library,
1875                      const FT_Byte*  file_base,
1876                      FT_Long         file_size,
1877                      FT_Long         face_index,
1878                      FT_Face        *aface );
1879
1880
1881  /*************************************************************************/
1882  /*                                                                       */
1883  /* <Function>                                                            */
1884  /*    FT_Open_Face                                                       */
1885  /*                                                                       */
1886  /* <Description>                                                         */
1887  /*    Opens a face object from a given resource and typeface index using */
1888  /*    an `FT_Open_Args' structure.  If the face object doesn't exist, it */
1889  /*    will be created.                                                   */
1890  /*                                                                       */
1891  /* <InOut>                                                               */
1892  /*    library    :: A handle to the library resource.                    */
1893  /*                                                                       */
1894  /* <Input>                                                               */
1895  /*    args       :: A pointer to an `FT_Open_Args' structure which must  */
1896  /*                  be filled by the caller.                             */
1897  /*                                                                       */
1898  /*    face_index :: The index of the face within the resource.  The      */
1899  /*                  first face has index 0.                              */
1900  /*                                                                       */
1901  /* <Output>                                                              */
1902  /*    aface      :: A handle to a new face object.                       */
1903  /*                                                                       */
1904  /* <Return>                                                              */
1905  /*    FreeType error code.  0 means success.                             */
1906  /*                                                                       */
1907  /* <Note>                                                                */
1908  /*    Unlike FreeType 1.x, this function automatically creates a glyph   */
1909  /*    slot for the face object which can be accessed directly through    */
1910  /*    `face->glyph'.                                                     */
1911  /*                                                                       */
1912  /*    @FT_Open_Face can be used to determine and/or check the font       */
1913  /*    format of a given font resource.  If the `face_index' field is     */
1914  /*    negative, the function will _not_ return any face handle in        */
1915  /*    `*aface'; the function's return value is 0 if the font format is   */
1916  /*    recognized, or non-zero otherwise.                                 */
1917  /*                                                                       */
1918  FT_EXPORT( FT_Error )
1919  FT_Open_Face( FT_Library           library,
1920                const FT_Open_Args*  args,
1921                FT_Long              face_index,
1922                FT_Face             *aface );
1923
1924
1925  /*************************************************************************/
1926  /*                                                                       */
1927  /* <Function>                                                            */
1928  /*    FT_Attach_File                                                     */
1929  /*                                                                       */
1930  /* <Description>                                                         */
1931  /*    `Attaches' a given font file to an existing face.  This is usually */
1932  /*    to read additional information for a single face object.  For      */
1933  /*    example, it is used to read the AFM files that come with Type 1    */
1934  /*    fonts in order to add kerning data and other metrics.              */
1935  /*                                                                       */
1936  /* <InOut>                                                               */
1937  /*    face         :: The target face object.                            */
1938  /*                                                                       */
1939  /* <Input>                                                               */
1940  /*    filepathname :: An 8-bit pathname naming the `metrics' file.       */
1941  /*                                                                       */
1942  /* <Return>                                                              */
1943  /*    FreeType error code.  0 means success.                             */
1944  /*                                                                       */
1945  /* <Note>                                                                */
1946  /*    If your font file is in memory, or if you want to provide your     */
1947  /*    own input stream object, use @FT_Attach_Stream.                    */
1948  /*                                                                       */
1949  /*    The meaning of the `attach' action (i.e., what really happens when */
1950  /*    the new file is read) is not fixed by FreeType itself.  It really  */
1951  /*    depends on the font format (and thus the font driver).             */
1952  /*                                                                       */
1953  /*    Client applications are expected to know what they are doing       */
1954  /*    when invoking this function.  Most drivers simply do not implement */
1955  /*    file attachments.                                                  */
1956  /*                                                                       */
1957  FT_EXPORT( FT_Error )
1958  FT_Attach_File( FT_Face      face,
1959                  const char*  filepathname );
1960
1961
1962  /*************************************************************************/
1963  /*                                                                       */
1964  /* <Function>                                                            */
1965  /*    FT_Attach_Stream                                                   */
1966  /*                                                                       */
1967  /* <Description>                                                         */
1968  /*    This function is similar to @FT_Attach_File with the exception     */
1969  /*    that it reads the attachment from an arbitrary stream.             */
1970  /*                                                                       */
1971  /* <InOut>                                                               */
1972  /*    face       :: The target face object.                              */
1973  /*                                                                       */
1974  /* <Input>                                                               */
1975  /*    parameters :: A pointer to an FT_Open_Args structure used to       */
1976  /*                  describe the input stream to FreeType.               */
1977  /* <Return>                                                              */
1978  /*    FreeType error code.  0 means success.                             */
1979  /*                                                                       */
1980  /* <Note>                                                                */
1981  /*    The meaning of the `attach' (i.e. what really happens when the     */
1982  /*    new file is read) is not fixed by FreeType itself.  It really      */
1983  /*    depends on the font format (and thus the font driver).             */
1984  /*                                                                       */
1985  /*    Client applications are expected to know what they are doing       */
1986  /*    when invoking this function.  Most drivers simply do not implement */
1987  /*    file attachments.                                                  */
1988  /*                                                                       */
1989  FT_EXPORT( FT_Error )
1990  FT_Attach_Stream( FT_Face        face,
1991                    FT_Open_Args*  parameters );
1992
1993
1994  /*************************************************************************/
1995  /*                                                                       */
1996  /* <Function>                                                            */
1997  /*    FT_Done_Face                                                       */
1998  /*                                                                       */
1999  /* <Description>                                                         */
2000  /*    Discards a given face object, as well as all of its child slots    */
2001  /*    and sizes.                                                         */
2002  /*                                                                       */
2003  /* <Input>                                                               */
2004  /*    face :: A handle to a target face object.                          */
2005  /*                                                                       */
2006  /* <Return>                                                              */
2007  /*    FreeType error code.  0 means success.                             */
2008  /*                                                                       */
2009  FT_EXPORT( FT_Error )
2010  FT_Done_Face( FT_Face  face );
2011
2012
2013  /*************************************************************************/
2014  /*                                                                       */
2015  /* <Function>                                                            */
2016  /*    FT_Set_Char_Size                                                   */
2017  /*                                                                       */
2018  /* <Description>                                                         */
2019  /*    Sets the character dimensions of a given face object.  The         */
2020  /*    `char_width' and `char_height' values are used for the width and   */
2021  /*    height, respectively, expressed in 26.6 fractional points.         */
2022  /*                                                                       */
2023  /*    If the horizontal or vertical resolution values are zero, a        */
2024  /*    default value of 72dpi is used.  Similarly, if one of the          */
2025  /*    character dimensions is zero, its value is set equal to the other. */
2026  /*                                                                       */
2027  /* <InOut>                                                               */
2028  /*    face            :: A handle to a target face object.               */
2029  /*                                                                       */
2030  /* <Input>                                                               */
2031  /*    char_width      :: The character width, in 26.6 fractional points. */
2032  /*                                                                       */
2033  /*    char_height     :: The character height, in 26.6 fractional        */
2034  /*                       points.                                         */
2035  /*                                                                       */
2036  /*    horz_resolution :: The horizontal resolution.                      */
2037  /*                                                                       */
2038  /*    vert_resolution :: The vertical resolution.                        */
2039  /*                                                                       */
2040  /* <Return>                                                              */
2041  /*    FreeType error code.  0 means success.                             */
2042  /*                                                                       */
2043  /* <Note>                                                                */
2044  /*    For BDF and PCF formats, this function uses the `PIXEL_SIZE'       */
2045  /*    property of the bitmap font; the `char_width' parameter is         */
2046  /*    ignored.                                                           */
2047  /*                                                                       */
2048  FT_EXPORT( FT_Error )
2049  FT_Set_Char_Size( FT_Face     face,
2050                    FT_F26Dot6  char_width,
2051                    FT_F26Dot6  char_height,
2052                    FT_UInt     horz_resolution,
2053                    FT_UInt     vert_resolution );
2054
2055
2056  /*************************************************************************/
2057  /*                                                                       */
2058  /* <Function>                                                            */
2059  /*    FT_Set_Pixel_Sizes                                                 */
2060  /*                                                                       */
2061  /* <Description>                                                         */
2062  /*    Sets the character dimensions of a given face object.  The width   */
2063  /*    and height are expressed in integer pixels.                        */
2064  /*                                                                       */
2065  /*    If one of the character dimensions is zero, its value is set equal */
2066  /*    to the other.                                                      */
2067  /*                                                                       */
2068  /* <InOut>                                                               */
2069  /*    face         :: A handle to the target face object.                */
2070  /*                                                                       */
2071  /* <Input>                                                               */
2072  /*    pixel_width  :: The character width, in integer pixels.            */
2073  /*                                                                       */
2074  /*    pixel_height :: The character height, in integer pixels.           */
2075  /*                                                                       */
2076  /* <Return>                                                              */
2077  /*    FreeType error code.  0 means success.                             */
2078  /*                                                                       */
2079  /* <Note>                                                                */
2080  /*    The values of `pixel_width' and `pixel_height' correspond to the   */
2081  /*    pixel values of the _typographic_ character size, which are NOT    */
2082  /*    necessarily the same as the dimensions of the glyph `bitmap        */
2083  /*    cells'.                                                            */
2084  /*                                                                       */
2085  /*    The `character size' is really the size of an abstract square      */
2086  /*    called the `EM', used to design the font.  However, depending      */
2087  /*    on the font design, glyphs will be smaller or greater than the     */
2088  /*    EM.                                                                */
2089  /*                                                                       */
2090  /*    This means that setting the pixel size to, say, 8x8 doesn't        */
2091  /*    guarantee in any way that you will get glyph bitmaps that all fit  */
2092  /*    within an 8x8 cell (sometimes even far from it).                   */
2093  /*                                                                       */
2094  /*    For bitmap fonts, `pixel_height' usually is a reliable value for   */
2095  /*    the height of the bitmap cell.  Drivers for bitmap font formats    */
2096  /*    which contain a single bitmap strike only (BDF, PCF, FNT) ignore   */
2097  /*    `pixel_width'.                                                     */
2098  /*                                                                       */
2099  /*    For BDF and PCF formats, this function uses the sum of the         */
2100  /*    `FONT_ASCENT' and `FONT_DESCENT' properties of the bitmap font.    */
2101  /*                                                                       */
2102  FT_EXPORT( FT_Error )
2103  FT_Set_Pixel_Sizes( FT_Face  face,
2104                      FT_UInt  pixel_width,
2105                      FT_UInt  pixel_height );
2106
2107
2108  /*************************************************************************/
2109  /*                                                                       */
2110  /* <Function>                                                            */
2111  /*    FT_Load_Glyph                                                      */
2112  /*                                                                       */
2113  /* <Description>                                                         */
2114  /*    A function used to load a single glyph within a given glyph slot,  */
2115  /*    for a given size.                                                  */
2116  /*                                                                       */
2117  /* <InOut>                                                               */
2118  /*    face        :: A handle to the target face object where the glyph  */
2119  /*                   will be loaded.                                     */
2120  /*                                                                       */
2121  /* <Input>                                                               */
2122  /*    glyph_index :: The index of the glyph in the font file.  For       */
2123  /*                   CID-keyed fonts (either in PS or in CFF format)     */
2124  /*                   this argument specifies the CID value.              */
2125  /*                                                                       */
2126  /*    load_flags  :: A flag indicating what to load for this glyph.  The */
2127  /*                   @FT_LOAD_XXX constants can be used to control the   */
2128  /*                   glyph loading process (e.g., whether the outline    */
2129  /*                   should be scaled, whether to load bitmaps or not,   */
2130  /*                   whether to hint the outline, etc).                  */
2131  /*                                                                       */
2132  /* <Return>                                                              */
2133  /*    FreeType error code.  0 means success.                             */
2134  /*                                                                       */
2135  /* <Note>                                                                */
2136  /*    If the glyph image is not a bitmap, and if the bit flag            */
2137  /*    FT_LOAD_IGNORE_TRANSFORM is unset, the glyph image will be         */
2138  /*    transformed with the information passed to a previous call to      */
2139  /*    @FT_Set_Transform.                                                 */
2140  /*                                                                       */
2141  /*    Note that this also transforms the `face.glyph.advance' field, but */
2142  /*    *not* the values in `face.glyph.metrics'.                          */
2143  /*                                                                       */
2144  FT_EXPORT( FT_Error )
2145  FT_Load_Glyph( FT_Face   face,
2146                 FT_UInt   glyph_index,
2147                 FT_Int32  load_flags );
2148
2149
2150  /*************************************************************************/
2151  /*                                                                       */
2152  /* <Function>                                                            */
2153  /*    FT_Load_Char                                                       */
2154  /*                                                                       */
2155  /* <Description>                                                         */
2156  /*    A function used to load a single glyph within a given glyph slot,  */
2157  /*    for a given size, according to its character code.                 */
2158  /*                                                                       */
2159  /* <InOut>                                                               */
2160  /*    face        :: A handle to a target face object where the glyph    */
2161  /*                   will be loaded.                                     */
2162  /*                                                                       */
2163  /* <Input>                                                               */
2164  /*    char_code   :: The glyph's character code, according to the        */
2165  /*                   current charmap used in the face.                   */
2166  /*                                                                       */
2167  /*    load_flags  :: A flag indicating what to load for this glyph.  The */
2168  /*                   @FT_LOAD_XXX constants can be used to control the   */
2169  /*                   glyph loading process (e.g., whether the outline    */
2170  /*                   should be scaled, whether to load bitmaps or not,   */
2171  /*                   whether to hint the outline, etc).                  */
2172  /*                                                                       */
2173  /* <Return>                                                              */
2174  /*    FreeType error code.  0 means success.                             */
2175  /*                                                                       */
2176  /* <Note>                                                                */
2177  /*    If the face has no current charmap, or if the character code       */
2178  /*    is not defined in the charmap, this function will return an        */
2179  /*    error.                                                             */
2180  /*                                                                       */
2181  /*    If the glyph image is not a bitmap, and if the bit flag            */
2182  /*    FT_LOAD_IGNORE_TRANSFORM is unset, the glyph image will be         */
2183  /*    transformed with the information passed to a previous call to      */
2184  /*    @FT_Set_Transform.                                                 */
2185  /*                                                                       */
2186  /*    Note that this also transforms the `face.glyph.advance' field, but */
2187  /*    *not* the values in `face.glyph.metrics'.                          */
2188  /*                                                                       */
2189  FT_EXPORT( FT_Error )
2190  FT_Load_Char( FT_Face   face,
2191                FT_ULong  char_code,
2192                FT_Int32  load_flags );
2193
2194
2195 /***************************************************************************
2196  *
2197  * @enum:
2198  *   FT_LOAD_XXX
2199  *
2200  * @description:
2201  *   A list of bit-field constants, used with @FT_Load_Glyph to indicate
2202  *   what kind of operations to perform during glyph loading.
2203  *
2204  * @values:
2205  *   FT_LOAD_DEFAULT ::
2206  *     Corresponding to 0, this value is used a default glyph load.  In this
2207  *     case, the following will happen:
2208  *
2209  *     1. FreeType looks for a bitmap for the glyph corresponding to the
2210  *        face's current size.  If one is found, the function returns.  The
2211  *        bitmap data can be accessed from the glyph slot (see note below).
2212  *
2213  *     2. If no embedded bitmap is searched or found, FreeType looks for a
2214  *        scalable outline.  If one is found, it is loaded from the font
2215  *        file, scaled to device pixels, then "hinted" to the pixel grid in
2216  *        order to optimize it.  The outline data can be accessed from the
2217  *        glyph slot (see note below).
2218  *
2219  *     Note that by default, the glyph loader doesn't render outlines into
2220  *     bitmaps.  The following flags are used to modify this default
2221  *     behaviour to more specific and useful cases.
2222  *
2223  *   FT_LOAD_NO_SCALE ::
2224  *     Don't scale the vector outline being loaded to 26.6 fractional
2225  *     pixels, but kept in font units.  Note that this also disables
2226  *     hinting and the loading of embedded bitmaps.  You should only use it
2227  *     when you want to retrieve the original glyph outlines in font units.
2228  *
2229  *   FT_LOAD_NO_HINTING ::
2230  *     Don't hint glyph outlines after their scaling to device pixels.
2231  *     This generally generates "blurrier" glyphs in anti-aliased modes.
2232  *
2233  *     This flag is ignored if @FT_LOAD_NO_SCALE is set.
2234  *
2235  *   FT_LOAD_RENDER ::
2236  *     Render the glyph outline immediately into a bitmap before the glyph
2237  *     loader returns.  By default, the glyph is rendered for the
2238  *     @FT_RENDER_MODE_NORMAL mode, which corresponds to 8-bit anti-aliased
2239  *     bitmaps using 256 opacity levels.  You can use either
2240  *     @FT_LOAD_TARGET_MONO or @FT_LOAD_MONOCHROME to render 1-bit
2241  *     monochrome bitmaps.
2242  *
2243  *     This flag is ignored if @FT_LOAD_NO_SCALE is set.
2244  *
2245  *   FT_LOAD_NO_BITMAP ::
2246  *     Don't look for bitmaps when loading the glyph.  Only scalable
2247  *     outlines will be loaded when available, and scaled, hinted, or
2248  *     rendered depending on other bit flags.
2249  *
2250  *     This does not prevent you from rendering outlines to bitmaps
2251  *     with @FT_LOAD_RENDER, however.
2252  *
2253  *   FT_LOAD_VERTICAL_LAYOUT ::
2254  *     Prepare the glyph image for vertical text layout.  This basically
2255  *     means that `face.glyph.advance' will correspond to the vertical
2256  *     advance height (instead of the default horizontal advance width),
2257  *     and that the glyph image will be translated to match the vertical
2258  *     bearings positions.
2259  *
2260  *   FT_LOAD_FORCE_AUTOHINT ::
2261  *     Force the use of the FreeType auto-hinter when a glyph outline is
2262  *     loaded.  You shouldn't need this in a typical application, since it
2263  *     is mostly used to experiment with its algorithm.
2264  *
2265  *   FT_LOAD_CROP_BITMAP ::
2266  *     Indicates that the glyph loader should try to crop the bitmap (i.e.,
2267  *     remove all space around its black bits) when loading it.  This is
2268  *     only useful when loading embedded bitmaps in certain fonts, since
2269  *     bitmaps rendered with @FT_LOAD_RENDER are always cropped by default.
2270  *
2271  *   FT_LOAD_PEDANTIC ::
2272  *     Indicates that the glyph loader should perform pedantic
2273  *     verifications during glyph loading, rejecting invalid fonts.  This
2274  *     is mostly used to detect broken glyphs in fonts.  By default,
2275  *     FreeType tries to handle broken fonts also.
2276  *
2277  *   FT_LOAD_IGNORE_GLOBAL_ADVANCE_WIDTH ::
2278  *     Indicates that the glyph loader should ignore the global advance
2279  *     width defined in the font.  For historical reasons (to support
2280  *     buggy CJK fonts), FreeType uses the value of the `advanceWidthMax'
2281  *     field in the `htmx' table for all glyphs if the font is monospaced.
2282  *     Activating this flags makes FreeType use the metric values given in
2283  *     the `htmx' table.
2284  *
2285  *   FT_LOAD_NO_RECURSE ::
2286  *     This flag is only used internally.  It merely indicates that the
2287  *     glyph loader should not load composite glyphs recursively.  Instead,
2288  *     it should set the `num_subglyph' and `subglyphs' values of the glyph
2289  *     slot accordingly, and set "glyph->format" to
2290  *     @FT_GLYPH_FORMAT_COMPOSITE.
2291  *
2292  *     The description of sub-glyphs is not available to client
2293  *     applications for now.
2294  *
2295  *   FT_LOAD_IGNORE_TRANSFORM ::
2296  *     Indicates that the glyph loader should not try to transform the
2297  *     loaded glyph image.  This doesn't prevent scaling, hinting, or
2298  *     rendering.
2299  *
2300  *   FT_LOAD_MONOCHROME ::
2301  *     This flag is used with @FT_LOAD_RENDER to indicate that you want
2302  *     to render a 1-bit monochrome glyph bitmap from a vectorial outline.
2303  *
2304  *     Note that this has no effect on the hinting algorithm used by the
2305  *     glyph loader.  You should better use @FT_LOAD_TARGET_MONO if you
2306  *     want to render monochrome-optimized glyph images instead.
2307  *
2308  *   FT_LOAD_LINEAR_DESIGN ::
2309  *     Return the linearly scaled metrics expressed in original font units
2310  *     instead of the default 16.16 pixel values.
2311  *
2312  *   FT_LOAD_NO_AUTOHINT ::
2313  *     Indicates that the auto-hinter should never be used to hint glyph
2314  *     outlines.  This doesn't prevent native format-specific hinters from
2315  *     being used.  This can be important for certain fonts where unhinted
2316  *     output is better than auto-hinted one.
2317  *
2318  *   FT_LOAD_TARGET_NORMAL ::
2319  *     Use hinting for @FT_RENDER_MODE_NORMAL.
2320  *
2321  *   FT_LOAD_TARGET_LIGHT ::
2322  *     Use hinting for @FT_RENDER_MODE_LIGHT.
2323  *
2324  *   FT_LOAD_TARGET_MONO ::
2325  *     Use hinting for @FT_RENDER_MODE_MONO.
2326  *
2327  *   FT_LOAD_TARGET_LCD ::
2328  *     Use hinting for @FT_RENDER_MODE_LCD.
2329  *
2330  *   FT_LOAD_TARGET_LCD_V ::
2331  *     Use hinting for @FT_RENDER_MODE_LCD_V.
2332  */
2333#define FT_LOAD_DEFAULT                      0x0
2334#define FT_LOAD_NO_SCALE                     0x1
2335#define FT_LOAD_NO_HINTING                   0x2
2336#define FT_LOAD_RENDER                       0x4
2337#define FT_LOAD_NO_BITMAP                    0x8
2338#define FT_LOAD_VERTICAL_LAYOUT              0x10
2339#define FT_LOAD_FORCE_AUTOHINT               0x20
2340#define FT_LOAD_CROP_BITMAP                  0x40
2341#define FT_LOAD_PEDANTIC                     0x80
2342#define FT_LOAD_IGNORE_GLOBAL_ADVANCE_WIDTH  0x200
2343#define FT_LOAD_NO_RECURSE                   0x400
2344#define FT_LOAD_IGNORE_TRANSFORM             0x800
2345#define FT_LOAD_MONOCHROME                   0x1000
2346#define FT_LOAD_LINEAR_DESIGN                0x2000
2347
2348  /* temporary hack! */
2349#define FT_LOAD_SBITS_ONLY                   0x4000
2350#define FT_LOAD_NO_AUTOHINT                  0x8000U
2351
2352  /* */
2353
2354#define FT_LOAD_TARGET_( x )      ( (FT_Int32)( (x) & 15 ) << 16 )
2355#define FT_LOAD_TARGET_MODE( x )  ( (FT_Render_Mode)( ( (x) >> 16 ) & 15 ) )
2356
2357#define FT_LOAD_TARGET_NORMAL     FT_LOAD_TARGET_( FT_RENDER_MODE_NORMAL )
2358#define FT_LOAD_TARGET_LIGHT      FT_LOAD_TARGET_( FT_RENDER_MODE_LIGHT  )
2359#define FT_LOAD_TARGET_MONO       FT_LOAD_TARGET_( FT_RENDER_MODE_MONO   )
2360#define FT_LOAD_TARGET_LCD        FT_LOAD_TARGET_( FT_RENDER_MODE_LCD    )
2361#define FT_LOAD_TARGET_LCD_V      FT_LOAD_TARGET_( FT_RENDER_MODE_LCD_V  )
2362
2363  /* */
2364
2365
2366  /*************************************************************************/
2367  /*                                                                       */
2368  /* <Function>                                                            */
2369  /*    FT_Set_Transform                                                   */
2370  /*                                                                       */
2371  /* <Description>                                                         */
2372  /*    A function used to set the transformation that is applied to glyph */
2373  /*    images when they are loaded into a glyph slot through              */
2374  /*    @FT_Load_Glyph.                                                    */
2375  /*                                                                       */
2376  /* <InOut>                                                               */
2377  /*    face   :: A handle to the source face object.                      */
2378  /*                                                                       */
2379  /* <Input>                                                               */
2380  /*    matrix :: A pointer to the transformation's 2x2 matrix.  Use 0 for */
2381  /*              the identity matrix.                                     */
2382  /*    delta  :: A pointer to the translation vector.  Use 0 for the null */
2383  /*              vector.                                                  */
2384  /*                                                                       */
2385  /* <Note>                                                                */
2386  /*    The transformation is only applied to scalable image formats after */
2387  /*    the glyph has been loaded.  It means that hinting is unaltered by  */
2388  /*    the transformation and is performed on the character size given in */
2389  /*    the last call to @FT_Set_Char_Size or @FT_Set_Pixel_Sizes.         */
2390  /*                                                                       */
2391  FT_EXPORT( void )
2392  FT_Set_Transform( FT_Face     face,
2393                    FT_Matrix*  matrix,
2394                    FT_Vector*  delta );
2395
2396
2397  /*************************************************************************/
2398  /*                                                                       */
2399  /* <Enum>                                                                */
2400  /*    FT_Render_Mode                                                     */
2401  /*                                                                       */
2402  /* <Description>                                                         */
2403  /*    An enumeration type that lists the render modes supported by       */
2404  /*    FreeType 2.  Each mode corresponds to a specific type of scanline  */
2405  /*    conversion performed on the outline, as well as specific           */
2406  /*    hinting optimizations.                                             */
2407  /*                                                                       */
2408  /*    For bitmap fonts the `bitmap->pixel_mode' field in the             */
2409  /*    @FT_GlyphSlotRec structure gives the format of the returned        */
2410  /*    bitmap.                                                            */
2411  /*                                                                       */
2412  /* <Values>                                                              */
2413  /*    FT_RENDER_MODE_NORMAL ::                                           */
2414  /*      This is the default render mode; it corresponds to 8-bit         */
2415  /*      anti-aliased bitmaps, using 256 levels of opacity.               */
2416  /*                                                                       */
2417  /*    FT_RENDER_MODE_LIGHT ::                                            */
2418  /*      This is similar to @FT_RENDER_MODE_NORMAL -- you have to use     */
2419  /*      @FT_LOAD_TARGET_LIGHT in calls to @FT_Load_Glyph to get any      */
2420  /*      effect since the rendering process no longer influences the      */
2421  /*      positioning of glyph outlines.                                   */
2422  /*                                                                       */
2423  /*      The resulting glyph shapes are more similar to the original,     */
2424  /*      while being a bit more fuzzy (`better shapes' instead of `better */
2425  /*      contrast', so to say.                                            */
2426  /*                                                                       */
2427  /*    FT_RENDER_MODE_MONO ::                                             */
2428  /*      This mode corresponds to 1-bit bitmaps.                          */
2429  /*                                                                       */
2430  /*    FT_RENDER_MODE_LCD ::                                              */
2431  /*      This mode corresponds to horizontal RGB/BGR sub-pixel displays,  */
2432  /*      like LCD-screens.  It produces 8-bit bitmaps that are 3 times    */
2433  /*      the width of the original glyph outline in pixels, and which use */
2434  /*      the @FT_PIXEL_MODE_LCD mode.                                     */
2435  /*                                                                       */
2436  /*    FT_RENDER_MODE_LCD_V ::                                            */
2437  /*      This mode corresponds to vertical RGB/BGR sub-pixel displays     */
2438  /*      (like PDA screens, rotated LCD displays, etc.).  It produces     */
2439  /*      8-bit bitmaps that are 3 times the height of the original        */
2440  /*      glyph outline in pixels and use the @FT_PIXEL_MODE_LCD_V mode.   */
2441  /*                                                                       */
2442  /* <Note>                                                                */
2443  /*   The LCD-optimized glyph bitmaps produced by FT_Render_Glyph are     */
2444  /*   _not filtered_ to reduce color-fringes.  It is up to the caller to  */
2445  /*   perform this pass.                                                  */
2446  /*                                                                       */
2447  typedef enum  FT_Render_Mode_
2448  {
2449    FT_RENDER_MODE_NORMAL = 0,
2450    FT_RENDER_MODE_LIGHT,
2451    FT_RENDER_MODE_MONO,
2452    FT_RENDER_MODE_LCD,
2453    FT_RENDER_MODE_LCD_V,
2454
2455    FT_RENDER_MODE_MAX
2456
2457  } FT_Render_Mode;
2458
2459
2460  /*************************************************************************/
2461  /*                                                                       */
2462  /* <Enum>                                                                */
2463  /*    ft_render_mode_xxx                                                 */
2464  /*                                                                       */
2465  /* <Description>                                                         */
2466  /*    These constats are deprecated.  Use the corresponding              */
2467  /*    @FT_Render_Mode values instead.                                    */
2468  /*                                                                       */
2469  /* <Values>                                                              */
2470  /*   ft_render_mode_normal :: see @FT_RENDER_MODE_NORMAL                 */
2471  /*   ft_render_mode_mono   :: see @FT_RENDER_MODE_MONO                   */
2472  /*                                                                       */
2473#define ft_render_mode_normal  FT_RENDER_MODE_NORMAL
2474#define ft_render_mode_mono    FT_RENDER_MODE_MONO
2475
2476
2477  /*************************************************************************/
2478  /*                                                                       */
2479  /* <Function>                                                            */
2480  /*    FT_Render_Glyph                                                    */
2481  /*                                                                       */
2482  /* <Description>                                                         */
2483  /*    Converts a given glyph image to a bitmap.  It does so by           */
2484  /*    inspecting the glyph image format, find the relevant renderer, and */
2485  /*    invoke it.                                                         */
2486  /*                                                                       */
2487  /* <InOut>                                                               */
2488  /*    slot        :: A handle to the glyph slot containing the image to  */
2489  /*                   convert.                                            */
2490  /*                                                                       */
2491  /* <Input>                                                               */
2492  /*    render_mode :: This is the render mode used to render the glyph    */
2493  /*                   image into a bitmap.  See FT_Render_Mode for a list */
2494  /*                   of possible values.                                 */
2495  /*                                                                       */
2496  /* <Return>                                                              */
2497  /*    FreeType error code.  0 means success.                             */
2498  /*                                                                       */
2499  FT_EXPORT( FT_Error )
2500  FT_Render_Glyph( FT_GlyphSlot    slot,
2501                   FT_Render_Mode  render_mode );
2502
2503
2504  /*************************************************************************/
2505  /*                                                                       */
2506  /* <Enum>                                                                */
2507  /*    FT_Kerning_Mode                                                    */
2508  /*                                                                       */
2509  /* <Description>                                                         */
2510  /*    An enumeration used to specify which kerning values to return in   */
2511  /*    @FT_Get_Kerning.                                                   */
2512  /*                                                                       */
2513  /* <Values>                                                              */
2514  /*    FT_KERNING_DEFAULT  :: Return scaled and grid-fitted kerning       */
2515  /*                           distances (value is 0).                     */
2516  /*                                                                       */
2517  /*    FT_KERNING_UNFITTED :: Return scaled but un-grid-fitted kerning    */
2518  /*                           distances.                                  */
2519  /*                                                                       */
2520  /*    FT_KERNING_UNSCALED :: Return the kerning vector in original font  */
2521  /*                           units.                                      */
2522  /*                                                                       */
2523  typedef enum  FT_Kerning_Mode_
2524  {
2525    FT_KERNING_DEFAULT  = 0,
2526    FT_KERNING_UNFITTED,
2527    FT_KERNING_UNSCALED
2528
2529  } FT_Kerning_Mode;
2530
2531
2532  /*************************************************************************/
2533  /*                                                                       */
2534  /* <Const>                                                               */
2535  /*    ft_kerning_default                                                 */
2536  /*                                                                       */
2537  /* <Description>                                                         */
2538  /*    This constant is deprecated.  Please use @FT_KERNING_DEFAULT       */
2539  /*    instead.                                                           */
2540  /*                                                                       */
2541#define ft_kerning_default   FT_KERNING_DEFAULT
2542
2543
2544  /*************************************************************************/
2545  /*                                                                       */
2546  /* <Const>                                                               */
2547  /*    ft_kerning_unfitted                                                */
2548  /*                                                                       */
2549  /* <Description>                                                         */
2550  /*    This constant is deprecated.  Please use @FT_KERNING_UNFITTED      */
2551  /*    instead.                                                           */
2552  /*                                                                       */
2553#define ft_kerning_unfitted  FT_KERNING_UNFITTED
2554
2555
2556  /*************************************************************************/
2557  /*                                                                       */
2558  /* <Const>                                                               */
2559  /*    ft_kerning_unscaled                                                */
2560  /*                                                                       */
2561  /* <Description>                                                         */
2562  /*    This constant is deprecated.  Please use @FT_KERNING_UNSCALED      */
2563  /*    instead.                                                           */
2564  /*                                                                       */
2565#define ft_kerning_unscaled  FT_KERNING_UNSCALED
2566
2567
2568  /*************************************************************************/
2569  /*                                                                       */
2570  /* <Function>                                                            */
2571  /*    FT_Get_Kerning                                                     */
2572  /*                                                                       */
2573  /* <Description>                                                         */
2574  /*    Returns the kerning vector between two glyphs of a same face.      */
2575  /*                                                                       */
2576  /* <Input>                                                               */
2577  /*    face        :: A handle to a source face object.                   */
2578  /*                                                                       */
2579  /*    left_glyph  :: The index of the left glyph in the kern pair.       */
2580  /*                                                                       */
2581  /*    right_glyph :: The index of the right glyph in the kern pair.      */
2582  /*                                                                       */
2583  /*    kern_mode   :: See @FT_Kerning_Mode for more information.          */
2584  /*                   Determines the scale/dimension of the returned      */
2585  /*                   kerning vector.                                     */
2586  /*                                                                       */
2587  /* <Output>                                                              */
2588  /*    akerning    :: The kerning vector.  This is either in font units   */
2589  /*                   or in pixels (26.6 format) for scalable formats,    */
2590  /*                   and in pixels for fixed-sizes formats.              */
2591  /*                                                                       */
2592  /* <Return>                                                              */
2593  /*    FreeType error code.  0 means success.                             */
2594  /*                                                                       */
2595  /* <Note>                                                                */
2596  /*    Only horizontal layouts (left-to-right & right-to-left) are        */
2597  /*    supported by this method.  Other layouts, or more sophisticated    */
2598  /*    kernings, are out of the scope of this API function -- they can be */
2599  /*    implemented through format-specific interfaces.                    */
2600  /*                                                                       */
2601  FT_EXPORT( FT_Error )
2602  FT_Get_Kerning( FT_Face     face,
2603                  FT_UInt     left_glyph,
2604                  FT_UInt     right_glyph,
2605                  FT_UInt     kern_mode,
2606                  FT_Vector  *akerning );
2607
2608
2609  /*************************************************************************/
2610  /*                                                                       */
2611  /* <Function>                                                            */
2612  /*    FT_Get_Glyph_Name                                                  */
2613  /*                                                                       */
2614  /* <Description>                                                         */
2615  /*    Retrieves the ASCII name of a given glyph in a face.  This only    */
2616  /*    works for those faces where FT_HAS_GLYPH_NAME(face) returns true.  */
2617  /*                                                                       */
2618  /* <Input>                                                               */
2619  /*    face        :: A handle to a source face object.                   */
2620  /*                                                                       */
2621  /*    glyph_index :: The glyph index.                                    */
2622  /*                                                                       */
2623  /*    buffer_max  :: The maximal number of bytes available in the        */
2624  /*                   buffer.                                             */
2625  /*                                                                       */
2626  /* <Output>                                                              */
2627  /*    buffer      :: A pointer to a target buffer where the name will be */
2628  /*                   copied to.                                          */
2629  /*                                                                       */
2630  /* <Return>                                                              */
2631  /*    FreeType error code.  0 means success.                             */
2632  /*                                                                       */
2633  /* <Note>                                                                */
2634  /*    An error is returned if the face doesn't provide glyph names or if */
2635  /*    the glyph index is invalid.  In all cases of failure, the first    */
2636  /*    byte of `buffer' will be set to 0 to indicate an empty name.       */
2637  /*                                                                       */
2638  /*    The glyph name is truncated to fit within the buffer if it is too  */
2639  /*    long.  The returned string is always zero-terminated.              */
2640  /*                                                                       */
2641  /*    This function is not compiled within the library if the config     */
2642  /*    macro FT_CONFIG_OPTION_NO_GLYPH_NAMES is defined in                */
2643  /*    `include/freetype/config/ftoptions.h'                              */
2644  /*                                                                       */
2645  FT_EXPORT( FT_Error )
2646  FT_Get_Glyph_Name( FT_Face     face,
2647                     FT_UInt     glyph_index,
2648                     FT_Pointer  buffer,
2649                     FT_UInt     buffer_max );
2650
2651
2652  /*************************************************************************/
2653  /*                                                                       */
2654  /* <Function>                                                            */
2655  /*    FT_Get_Postscript_Name                                             */
2656  /*                                                                       */
2657  /* <Description>                                                         */
2658  /*    Retrieves the ASCII Postscript name of a given face, if available. */
2659  /*    This only works with Postscript and TrueType fonts.                */
2660  /*                                                                       */
2661  /* <Input>                                                               */
2662  /*    face :: A handle to the source face object.                        */
2663  /*                                                                       */
2664  /* <Return>                                                              */
2665  /*    A pointer to the face's Postscript name.  NULL if unavailable.     */
2666  /*                                                                       */
2667  /* <Note>                                                                */
2668  /*    The returned pointer is owned by the face and will be destroyed    */
2669  /*    with it.                                                           */
2670  /*                                                                       */
2671  FT_EXPORT( const char* )
2672  FT_Get_Postscript_Name( FT_Face  face );
2673
2674
2675  /*************************************************************************/
2676  /*                                                                       */
2677  /* <Function>                                                            */
2678  /*    FT_Select_Charmap                                                  */
2679  /*                                                                       */
2680  /* <Description>                                                         */
2681  /*    Selects a given charmap by its encoding tag (as listed in          */
2682  /*    `freetype.h').                                                     */
2683  /*                                                                       */
2684  /* <InOut>                                                               */
2685  /*    face     :: A handle to the source face object.                    */
2686  /*                                                                       */
2687  /* <Input>                                                               */
2688  /*    encoding :: A handle to the selected charmap.                      */
2689  /*                                                                       */
2690  /* <Return>                                                              */
2691  /*    FreeType error code.  0 means success.                             */
2692  /*                                                                       */
2693  /* <Note>                                                                */
2694  /*    This function will return an error if no charmap in the face       */
2695  /*    corresponds to the encoding queried here.                          */
2696  /*                                                                       */
2697  FT_EXPORT( FT_Error )
2698  FT_Select_Charmap( FT_Face      face,
2699                     FT_Encoding  encoding );
2700
2701
2702  /*************************************************************************/
2703  /*                                                                       */
2704  /* <Function>                                                            */
2705  /*    FT_Set_Charmap                                                     */
2706  /*                                                                       */
2707  /* <Description>                                                         */
2708  /*    Selects a given charmap for character code to glyph index          */
2709  /*    decoding.                                                          */
2710  /*                                                                       */
2711  /* <InOut>                                                               */
2712  /*    face    :: A handle to the source face object.                     */
2713  /*                                                                       */
2714  /* <Input>                                                               */
2715  /*    charmap :: A handle to the selected charmap.                       */
2716  /*                                                                       */
2717  /* <Return>                                                              */
2718  /*    FreeType error code.  0 means success.                             */
2719  /*                                                                       */
2720  /* <Note>                                                                */
2721  /*    This function will return an error if the charmap is not part of   */
2722  /*    the face (i.e., if it is not listed in the face->charmaps[]        */
2723  /*    table).                                                            */
2724  /*                                                                       */
2725  FT_EXPORT( FT_Error )
2726  FT_Set_Charmap( FT_Face     face,
2727                  FT_CharMap  charmap );
2728
2729
2730  /*************************************************************************/
2731  /*                                                                       */
2732  /* @function:                                                            */
2733  /*    FT_Get_Charmap_Index                                               */
2734  /*                                                                       */
2735  /* @description:                                                         */
2736  /*    Retrieve index of a given charmap.                                 */
2737  /*                                                                       */
2738  /* @input:                                                               */
2739  /*    charmap :: A handle to a charmap.                                  */
2740  /*                                                                       */
2741  /* @return:                                                              */
2742  /*    The index into the array of character maps within the face to      */
2743  /*    which `charmap' belongs.                                           */
2744  /*                                                                       */
2745  FT_EXPORT( FT_Int )
2746  FT_Get_Charmap_Index( FT_CharMap  charmap );
2747
2748
2749  /*************************************************************************/
2750  /*                                                                       */
2751  /* <Function>                                                            */
2752  /*    FT_Get_Char_Index                                                  */
2753  /*                                                                       */
2754  /* <Description>                                                         */
2755  /*    Returns the glyph index of a given character code.  This function  */
2756  /*    uses a charmap object to do the translation.                       */
2757  /*                                                                       */
2758  /* <Input>                                                               */
2759  /*    face     :: A handle to the source face object.                    */
2760  /*                                                                       */
2761  /*    charcode :: The character code.                                    */
2762  /*                                                                       */
2763  /* <Return>                                                              */
2764  /*    The glyph index.  0 means `undefined character code'.              */
2765  /*                                                                       */
2766  /* <Note>                                                                */
2767  /*    FreeType computes its own glyph indices which are not necessarily  */
2768  /*    the same as used in the font in case the font is based on glyph    */
2769  /*    indices.  Reason for this behaviour is to assure that index 0 is   */
2770  /*    never used, representing the missing glyph.                        */
2771  /*                                                                       */
2772  FT_EXPORT( FT_UInt )
2773  FT_Get_Char_Index( FT_Face   face,
2774                     FT_ULong  charcode );
2775
2776
2777  /*************************************************************************/
2778  /*                                                                       */
2779  /* <Function>                                                            */
2780  /*    FT_Get_First_Char                                                  */
2781  /*                                                                       */
2782  /* <Description>                                                         */
2783  /*    This function is used to return the first character code in the    */
2784  /*    current charmap of a given face.  It will also return the          */
2785  /*    corresponding glyph index.                                         */
2786  /*                                                                       */
2787  /* <Input>                                                               */
2788  /*    face    :: A handle to the source face object.                     */
2789  /*                                                                       */
2790  /* <Output>                                                              */
2791  /*    agindex :: Glyph index of first character code.  0 if charmap is   */
2792  /*               empty.                                                  */
2793  /*                                                                       */
2794  /* <Return>                                                              */
2795  /*    The charmap's first character code.                                */
2796  /*                                                                       */
2797  /* <Note>                                                                */
2798  /*    You should use this function with @FT_Get_Next_Char to be able to  */
2799  /*    parse all character codes available in a given charmap.  The code  */
2800  /*    should look like this:                                             */
2801  /*                                                                       */
2802  /*    {                                                                  */
2803  /*      FT_ULong  charcode;                                              */
2804  /*      FT_UInt   gindex;                                                */
2805  /*                                                                       */
2806  /*                                                                       */
2807  /*      charcode = FT_Get_First_Char( face, &gindex );                   */
2808  /*      while ( gindex != 0 )                                            */
2809  /*      {                                                                */
2810  /*        ... do something with (charcode,gindex) pair ...               */
2811  /*                                                                       */
2812  /*        charcode = FT_Get_Next_Char( face, charcode, &gindex );        */
2813  /*      }                                                                */
2814  /*    }                                                                  */
2815  /*                                                                       */
2816  /*    Note that `*agindex' will be set to 0 if the charmap is empty.     */
2817  /*    The result itself can be 0 in two cases: if the charmap is empty   */
2818  /*    or when the value 0 is the first valid character code.             */
2819  /*                                                                       */
2820  FT_EXPORT( FT_ULong )
2821  FT_Get_First_Char( FT_Face   face,
2822                     FT_UInt  *agindex );
2823
2824
2825  /*************************************************************************/
2826  /*                                                                       */
2827  /* <Function>                                                            */
2828  /*    FT_Get_Next_Char                                                   */
2829  /*                                                                       */
2830  /* <Description>                                                         */
2831  /*    This function is used to return the next character code in the     */
2832  /*    current charmap of a given face following the value 'char_code',   */
2833  /*    as well as the corresponding glyph index.                          */
2834  /*                                                                       */
2835  /* <Input>                                                               */
2836  /*    face      :: A handle to the source face object.                   */
2837  /*    char_code :: The starting character code.                          */
2838  /*                                                                       */
2839  /* <Output>                                                              */
2840  /*    agindex   :: Glyph index of first character code.  0 if charmap    */
2841  /*                 is empty.                                             */
2842  /*                                                                       */
2843  /* <Return>                                                              */
2844  /*    The charmap's next character code.                                 */
2845  /*                                                                       */
2846  /* <Note>                                                                */
2847  /*    You should use this function with @FT_Get_First_Char to walk       */
2848  /*    through all character codes available in a given charmap.  See     */
2849  /*    the note for this function for a simple code example.              */
2850  /*                                                                       */
2851  /*    Note that `*agindex' will be set to 0 when there are no more codes */
2852  /*    in the charmap.                                                    */
2853  /*                                                                       */
2854  FT_EXPORT( FT_ULong )
2855  FT_Get_Next_Char( FT_Face    face,
2856                    FT_ULong   char_code,
2857                    FT_UInt   *agindex );
2858
2859
2860  /*************************************************************************/
2861  /*                                                                       */
2862  /* <Function>                                                            */
2863  /*    FT_Get_Name_Index                                                  */
2864  /*                                                                       */
2865  /* <Description>                                                         */
2866  /*    Returns the glyph index of a given glyph name.  This function uses */
2867  /*    driver specific objects to do the translation.                     */
2868  /*                                                                       */
2869  /* <Input>                                                               */
2870  /*    face       :: A handle to the source face object.                  */
2871  /*                                                                       */
2872  /*    glyph_name :: The glyph name.                                      */
2873  /*                                                                       */
2874  /* <Return>                                                              */
2875  /*    The glyph index.  0 means `undefined character code'.              */
2876  /*                                                                       */
2877  FT_EXPORT( FT_UInt )
2878  FT_Get_Name_Index( FT_Face     face,
2879                     FT_String*  glyph_name );
2880
2881
2882
2883  /*************************************************************************/
2884  /*                                                                       */
2885  /* <Section>                                                             */
2886  /*    computations                                                       */
2887  /*                                                                       */
2888  /* <Title>                                                               */
2889  /*    Computations                                                       */
2890  /*                                                                       */
2891  /* <Abstract>                                                            */
2892  /*    Crunching fixed numbers and vectors.                               */
2893  /*                                                                       */
2894  /* <Description>                                                         */
2895  /*    This section contains various functions used to perform            */
2896  /*    computations on 16.16 fixed-float numbers or 2d vectors.           */
2897  /*                                                                       */
2898  /* <Order>                                                               */
2899  /*    FT_MulDiv                                                          */
2900  /*    FT_MulFix                                                          */
2901  /*    FT_DivFix                                                          */
2902  /*    FT_RoundFix                                                        */
2903  /*    FT_CeilFix                                                         */
2904  /*    FT_FloorFix                                                        */
2905  /*    FT_Vector_Transform                                                */
2906  /*    FT_Matrix_Multiply                                                 */
2907  /*    FT_Matrix_Invert                                                   */
2908  /*                                                                       */
2909  /*************************************************************************/
2910
2911
2912  /*************************************************************************/
2913  /*                                                                       */
2914  /* <Function>                                                            */
2915  /*    FT_MulDiv                                                          */
2916  /*                                                                       */
2917  /* <Description>                                                         */
2918  /*    A very simple function used to perform the computation `(a*b)/c'   */
2919  /*    with maximal accuracy (it uses a 64-bit intermediate integer       */
2920  /*    whenever necessary).                                               */
2921  /*                                                                       */
2922  /*    This function isn't necessarily as fast as some processor specific */
2923  /*    operations, but is at least completely portable.                   */
2924  /*                                                                       */
2925  /* <Input>                                                               */
2926  /*    a :: The first multiplier.                                         */
2927  /*    b :: The second multiplier.                                        */
2928  /*    c :: The divisor.                                                  */
2929  /*                                                                       */
2930  /* <Return>                                                              */
2931  /*    The result of `(a*b)/c'.  This function never traps when trying to */
2932  /*    divide by zero; it simply returns `MaxInt' or `MinInt' depending   */
2933  /*    on the signs of `a' and `b'.                                       */
2934  /*                                                                       */
2935  FT_EXPORT( FT_Long )
2936  FT_MulDiv( FT_Long  a,
2937             FT_Long  b,
2938             FT_Long  c );
2939
2940
2941  /*************************************************************************/
2942  /*                                                                       */
2943  /* <Function>                                                            */
2944  /*    FT_MulFix                                                          */
2945  /*                                                                       */
2946  /* <Description>                                                         */
2947  /*    A very simple function used to perform the computation             */
2948  /*    `(a*b)/0x10000' with maximal accuracy.  Most of the time this is   */
2949  /*    used to multiply a given value by a 16.16 fixed float factor.      */
2950  /*                                                                       */
2951  /* <Input>                                                               */
2952  /*    a :: The first multiplier.                                         */
2953  /*    b :: The second multiplier.  Use a 16.16 factor here whenever      */
2954  /*         possible (see note below).                                    */
2955  /*                                                                       */
2956  /* <Return>                                                              */
2957  /*    The result of `(a*b)/0x10000'.                                     */
2958  /*                                                                       */
2959  /* <Note>                                                                */
2960  /*    This function has been optimized for the case where the absolute   */
2961  /*    value of `a' is less than 2048, and `b' is a 16.16 scaling factor. */
2962  /*    As this happens mainly when scaling from notional units to         */
2963  /*    fractional pixels in FreeType, it resulted in noticeable speed     */
2964  /*    improvements between versions 2.x and 1.x.                         */
2965  /*                                                                       */
2966  /*    As a conclusion, always try to place a 16.16 factor as the         */
2967  /*    _second_ argument of this function; this can make a great          */
2968  /*    difference.                                                        */
2969  /*                                                                       */
2970  FT_EXPORT( FT_Long )
2971  FT_MulFix( FT_Long  a,
2972             FT_Long  b );
2973
2974
2975  /*************************************************************************/
2976  /*                                                                       */
2977  /* <Function>                                                            */
2978  /*    FT_DivFix                                                          */
2979  /*                                                                       */
2980  /* <Description>                                                         */
2981  /*    A very simple function used to perform the computation             */
2982  /*    `(a*0x10000)/b' with maximal accuracy.  Most of the time, this is  */
2983  /*    used to divide a given value by a 16.16 fixed float factor.        */
2984  /*                                                                       */
2985  /* <Input>                                                               */
2986  /*    a :: The first multiplier.                                         */
2987  /*    b :: The second multiplier.  Use a 16.16 factor here whenever      */
2988  /*         possible (see note below).                                    */
2989  /*                                                                       */
2990  /* <Return>                                                              */
2991  /*    The result of `(a*0x10000)/b'.                                     */
2992  /*                                                                       */
2993  /* <Note>                                                                */
2994  /*    The optimization for FT_DivFix() is simple: If (a << 16) fits in   */
2995  /*    32 bits, then the division is computed directly.  Otherwise, we    */
2996  /*    use a specialized version of @FT_MulDiv.                           */
2997  /*                                                                       */
2998  FT_EXPORT( FT_Long )
2999  FT_DivFix( FT_Long  a,
3000             FT_Long  b );
3001
3002
3003  /*************************************************************************/
3004  /*                                                                       */
3005  /* <Function>                                                            */
3006  /*    FT_RoundFix                                                        */
3007  /*                                                                       */
3008  /* <Description>                                                         */
3009  /*    A very simple function used to round a 16.16 fixed number.         */
3010  /*                                                                       */
3011  /* <Input>                                                               */
3012  /*    a :: The number to be rounded.                                     */
3013  /*                                                                       */
3014  /* <Return>                                                              */
3015  /*    The result of `(a + 0x8000) & -0x10000'.                           */
3016  /*                                                                       */
3017  FT_EXPORT( FT_Fixed )
3018  FT_RoundFix( FT_Fixed  a );
3019
3020
3021  /*************************************************************************/
3022  /*                                                                       */
3023  /* <Function>                                                            */
3024  /*    FT_CeilFix                                                         */
3025  /*                                                                       */
3026  /* <Description>                                                         */
3027  /*    A very simple function used to compute the ceiling function of a   */
3028  /*    16.16 fixed number.                                                */
3029  /*                                                                       */
3030  /* <Input>                                                               */
3031  /*    a :: The number for which the ceiling function is to be computed.  */
3032  /*                                                                       */
3033  /* <Return>                                                              */
3034  /*    The result of `(a + 0x10000 - 1) & -0x10000'.                      */
3035  /*                                                                       */
3036  FT_EXPORT( FT_Fixed )
3037  FT_CeilFix( FT_Fixed  a );
3038
3039
3040  /*************************************************************************/
3041  /*                                                                       */
3042  /* <Function>                                                            */
3043  /*    FT_FloorFix                                                        */
3044  /*                                                                       */
3045  /* <Description>                                                         */
3046  /*    A very simple function used to compute the floor function of a     */
3047  /*    16.16 fixed number.                                                */
3048  /*                                                                       */
3049  /* <Input>                                                               */
3050  /*    a :: The number for which the floor function is to be computed.    */
3051  /*                                                                       */
3052  /* <Return>                                                              */
3053  /*    The result of `a & -0x10000'.                                      */
3054  /*                                                                       */
3055  FT_EXPORT( FT_Fixed )
3056  FT_FloorFix( FT_Fixed  a );
3057
3058
3059  /*************************************************************************/
3060  /*                                                                       */
3061  /* <Function>                                                            */
3062  /*    FT_Vector_Transform                                                */
3063  /*                                                                       */
3064  /* <Description>                                                         */
3065  /*    Transforms a single vector through a 2x2 matrix.                   */
3066  /*                                                                       */
3067  /* <InOut>                                                               */
3068  /*    vector :: The target vector to transform.                          */
3069  /*                                                                       */
3070  /* <Input>                                                               */
3071  /*    matrix :: A pointer to the source 2x2 matrix.                      */
3072  /*                                                                       */
3073  /* <Note>                                                                */
3074  /*    The result is undefined if either `vector' or `matrix' is invalid. */
3075  /*                                                                       */
3076  FT_EXPORT( void )
3077  FT_Vector_Transform( FT_Vector*        vec,
3078                       const FT_Matrix*  matrix );
3079
3080
3081  /* */
3082
3083
3084FT_END_HEADER
3085
3086#endif /* __FREETYPE_H__ */
3087
3088
3089/* END */
Note: See TracBrowser for help on using the repository browser.