			The FreeType Engine

		       Core Library Reference


		-----------------------------------


			 Table of Contents:

			    Introduction
                         
                            I. Types
                         
                           II. Functions
                         
                          III. Error codes
                          

                        --------------------


Introduction:

  This  reference  presents the  types,  functions  and error  codes
  defined in the high-level API header file "freetype.h".  Note that
  all symbols defined  in this file are prefixed  by "TT_", to avoid
  name conflicts with other packages at link time.

  Some of its  parts are also dedicated to  the extension that comes
  by default with this distribution of the library, which is kerning
  support.

----------------------------------------------------------------------------

I. Types:

  Here is  the list of  all the types  defined in the  core FreeType
  API.  Their exact definition can be found in the file "freetype.h"
  which should be included by every client application.


  TT_Fixed

    A  signed 16.16  fixed  float value  used  to specify  transform
    coefficients and other important data.

  ..................................................................

  TT_FWord

    A signed  16 bits value used  to express a  distance measured in
    the font's original EM units.  These are also called 'FUnits' in
    the TrueType specification.

  ..................................................................

  TT_UFWord

    Unsigned FWord.

  ..................................................................

  TT_Short
  TT_UShort
  TT_Long
  TT_ULong

    These four  types are  aliases for 16  bits integer  (signed and
    unsigned) and 32 bits one (signed and unsigned).

  ..................................................................

  TT_F2Dot14

    A  2.14 fixed  float integer  used  for unary  vectors and  some
    scaling coefficients. Their layout is:

      s : 1    -- sign bit
      m : 1    -- mantissa bit
      f : 14   -- unsigned fractional value

    where  's:m' is  the 2-bit  signed  integer value  to which  the
    always-positive fractional part 'f' should be added.

  ..................................................................

  TT_F26Dot6

    The  26.6 fixed  float format  used to  define  fractional pixel
    coordinates.  Here, 1 unit = 1/64 pixel.

  ..................................................................

  TT_UnitVector

    A simple  structure used to  store a unit vector.   The vector's
    coordinates are expressed in fixed float format (2.14).

      struct
      { 
        TT_F2Dot14  x;
        TT_F2Dot14  y;
      }

  ..................................................................

  TT_Vector

    A  simple   structure  used  to  store  a   single  vector.  Its
    coordinates are expressed in fixed float format (26.6).

      struct
      {
        TT_F26Dot6  x;
        TT_F26Dot6  y;
      }

  ..................................................................

  TT_Matrix

    A  simple structure  used to  store  a single  2x2 matrix.   Its
    coefficients are  expressed in  16.16 fixed float  format.  This
    matrix is  used to perform  linear transformations on  the glyph
    outline, such as slanting or rotation.

      struct
      {
        TT_Fixed  xx, xy;
        TT_Fixed  yx, yy;
      };

    The computation performed is:

       x' = xx * x  +  xy * y
       y' = yx * x  +  yy * y

  ..................................................................

  TT_Glyph_Outline

    This   structure  is   used  to   describe  a   vectorial  glyph
    representation to the rasterizer.  It is made of:

    - an array of points:

        The  'points'  field  gives  the  number of  points  in  the
        outline, while  their coordinates are found  in the parallel
        arrays 'xCoord'  and 'yCoord'.   The 'flag' array  holds for
        each point a flag indicating its type.

        Currently, only the first  bit (bit 0, the least significant
        bit)  of each byte  is meaningful  to the  rasterizer.  When
        set, it  indicates that the  point is _on_ the  curve.  When
        not set, the point is said to be _off_ the curve.  It's then
        a Bezier control point.

        For more  information about point states,  read the TrueType
        specification or the scan-line documentation "raster.txt".


    - an array of contours' start-point indexes:

        The 'contours' field gives the number of contours, while the
        'conStarts' array holds the  indexes of each contour's first
        point.  Note that  the first contour always starts  at 0 and
        has no entry in this table.

        Hence, conStarts[0]  holds the  index of the  point starting
        the _second_  contour.  The first  one being defined  by the
        closure of the path 0..conStarts[0]-1.

        ** IMPORTANT NOTE: **
        *********************

        The last table entry _must_  always give the total number of
        points used to draw the contours, i.e.:
        
             conStarts[contours-1] == points

        If  this value  is  bigger than  'points'  when calling  the
        scan-line converter,  the component will  immediately return
        an  error.   If  the  value  is  smaller,  only  the  points
        contained  in the  described contours  will be  used  in the
        conversion process.


    - a dropout mode:

        Used  to specify the  method to  apply for  drop-out control
        (also  called 'continuity  testing' in  other environments).
        The  mode value must  be one  of the  values defined  by the
        TrueType specification.

        The recent modes 4 and 5 introduced in the newest spec (1.6)
        are fully supported.

        An invalid  value (i.e.,  other than  0, 1, 2,  4, or  5) is
        taken as no dropout control (equivalent to mode 0).


   NOTE1:

     A typical user would only modify the point coordinates accessed
     through the 'xCoord' and  'yCoord' fields.  Changing the number
     of points,  the contours  arrays or even  the flags array  is a
     delicate process that should be taken seriously.

   NOTE2:

     A  glyph  outline  only  contains  pointers to  the  tables  it
     describes, but it doesn't own them!

     Typically,  the  tables  are  defined  and  owned  by  a  glyph
     container object (see below).  They are accessed through a call
     to  TT_Get_Glyph_Outline()  which  returns  a  TT_Glyph_Outline
     structure whose pointers relate to the container's data.

     These outline's  tables should never  be freed directly  by the
     client  application;  they will  be  destroyed  with the  glyph
     container when the latter is discarded.

    struct
    {
      unsigned int     contours;  /* number of contours in glyph   */
      unsigned short*  conStarts; /* points to an array of each
                                     contour's start point index   */
      unsigned int     points;    /* number of points in the glyph */
      long*            xCoord;    /* table of x coordinates        */
      long*            yCoord;    /* table of y coordinates        */
      unsigned char*   flag;      /* table of flags                */
  
      char             dropout_mode;  /* dropout mode */
    }

  ..................................................................

  TT_Glyph_Metrics

    A structure  used to return simple glyph  metrics.  These values
    are expressed in fractional  pixels (26.6 format) if scaling was
    active, and in FUnits otherwise.

      struct
      {
        TT_F26Dot6  leftSideBearing;
        TT_F26Dot6  advanceWidth;
    
        TT_F26Dot6  xMin, yMin, xMax, yMax;
      };

  ..................................................................

  TT_Instance_Metrics

    A structure used to return instance (point size) metrics.

      struct
      {
        int  pointSize;
        /* point size in points (1 point = 1/72 inch) */
    
        int  x_ppem;  /* horizontal pixels per EM square */
        int  y_ppem;  /* vertical pixels per EM square   */
    
        int  x_resolution; /* device horizontal resolution in dpi */
        int  y_resolution; /* device vertical resolution in dpi   */
      };

  ..................................................................

  TT_Raster_Map

    This structure is  used to describe a target  bitmap (or pixmap)
    to the  scan-line converter.   It must be  set up by  the client
    application.

    - the  'rows' field  contains the  total number  of rows  in the
      bitmap

    - the 'width' field gives the number of pixels per row (a bit or
      a byte, depending on the map's nature).

    - the  'cols' field  gives the  number of  columns,  i.e. bytes,
      taken by each row in the map buffer.

      ** IMPORTANT **: the 'cols' field must be a multiple of 4!

      Typically, its value should  be '(width+7)/8' for bitmaps, and
      '(width+3) & -4' for pixmaps.
      
    - the 'flow' field gives the map's vertical orientation.

      For example, if  the first bytes of the  bitmap buffer pertain
      to its upper row, the flow is said to be going 'down', and the
      field should  take the  value 'TT_Flow_Down'.  If  these bytes
      pertain to  its lowest  row, the flow  is going 'up',  and the
      value is 'TT_Flow_Up'.

      As an example, the PC video modes use a 'down' flow, where the
      first VRAM  byte corresponds to the upper  and leftmost corner
      of the screen.

    - the 'bitmap' field is a typeless pointer to the map's buffer.

    - the 'size' field  contains the buffer's size in  bytes.  It is
      usually computed as follows:

          size = rows * cols;

    NOTE:

      For  bitmaps, the leftmost-pixel  is   related to the  highest
      (i.e.  most significant) bit  of its byte.  There is currently
      no support for the opposite convention found in some systems.

      (It can  be easily added if  you really need it,  just ask the
      development team)

      struct
      {
        int     rows;    /* number of rows                    */
        int     cols;    /* number of columns (bytes) per row */
        int     width;   /* number of pixels per line         */
        int     flow;    /* bitmap orientation                */
    
        void*   bitmap;  /* bit/pixmap buffer                 */
        long    size;    /* bit/pixmap size in bytes          */
      } TT_Raster_Map;

  ..................................................................

  TT_Header

    This structure  is used to  hold the font's header.   Its layout
    and meaning  are defined in  the TrueType specification,  in the
    'head' section.

  ..................................................................

  TT_Horizontal_Header

    This  structure is used  to hold  the font's  horizontal header.
    Its   layout   and  meaning   are   defined   in  the   TrueType
    specification, in the 'hhead' section.

  ..................................................................

  TT_OS2

    This  structure is  used to  hold  the font's  OS/2 table.   Its
    layout and meaning are defined in the TrueType specification, in
    the 'OS/2' section.

  ..................................................................

  TT_Postscript

    This structure is used to hold the font's Postscript table.  Its
    layout and meaning are defined in the TrueType specification, in
    the 'post' section.

  ..................................................................

  TT_Face_Properties

    This structure  is used to  return an opened  face's properties.
    These are:

    - The total  number of  glyphs in the  font, given by  the field
      'num_Glyphs'.

    - The  maximum number  of points  for the  font's  glyphs.  This
      value  is  used to  allocate  the  points  tables of  a  glyph
      container's outline.  It can  be fairly large (like 256 points
      for Roman fonts).

    - The maximum  number of contours  for the font's  glyphs.  This
      value  is used  to allocate  the  contours tables  of a  glyph
      container's outline.  It can be fairly large (over 16, even in
      Roman fonts).

    - The maximum number of associated faces.  This number is always
      0 for  a normal  TrueType font file.   However, when  the face
      object was opened from  a TrueType collection, it contains the
      maximum embedded font index used within this font collection.

    - pointers to  the face's  header, horizontal header,  OS/2, and
      Postscript tables.

       struct
       {
         int  num_Glyphs;              /* number of glyphs in face */
         int  max_Points;   /* maximum number of points in a glyph */
         int  max_Contours;
                          /* maximum number of contours in a glyph */
     
         int  max_Faces;   /* 0 for normal TrueType files, and the */
                           /* number of embedded faces minus 1 for */
                           /* TrueType collections                 */
     
         TT_Header*             header;   /* TrueType header table */
         TT_Horizontal_Header*  horizontal;
                                     /* TrueType horizontal header */
         TT_OS2*                os2;        /* TrueType OS/2 table */
         TT_Postscript*         postscript;
                                      /* TrueType Postscript table */
       } TT_Face_Properties;

  ..................................................................

  TT_Stream

     This handle type defines a  stream used to access a font file's
     data.   A client  application  should never  deal with  streams
     directly,  but some  engine  extensions may  later  need it  to
     support more advanced features like font embedding.

  ..................................................................

  TT_Face

     This type  defines a  handle used to  reference a  face object.
     The   objects  are   never  accessed   directly  by   a  client
     application; it can only obtain handles to new objects, and use
     them to query specific information or processes.

     See also:

        TT_Open_Face(), TT_Open_Collection(), TT_Close_Face(),
        TT_Get_Face_Properties(), etc.

  ..................................................................

  TT_Instance

     This type defines a handle used to reference an instance object
     (also called a 'pointsize' in other type engines).  An instance
     is always  created from a  valid face object, and  is destroyed
     with it by the engine.

     See also:

       TT_New_Instance(), TT_Close_Instance(),
       TT_Set_Instance_Pointsize(), TT_Set_Instance_Resolution(),
       etc.

  ..................................................................

  TT_Glyph

     This type defines a handle  used to reference a glyph container
     object.  A glyph container is  an object owning tables sized to
     the font's  maximum profile to hold  any glyph of  a given font
     file.

     It  contains an  outline, some  metrics, as  well as  some data
     related  to the  way it  should be  processed by  the scan-line
     converter.

     Note  that a  glyph container  doesn't contain  any  bitmap nor
     pixmap!

     See also:

       TT_New_Glyph(), TT_Close_Glyph(), TT_Get_Glyph_Metrics(),
       TT_Get_Glyph_Outline(), TT_Get_Glyph_Bitmap(),
       TT_Get_Glyph_Pixmap()

  ..................................................................

  TT_Error

    This is the type of all error codes returned by the API.  Nearly
    all functions return an error code, set to 0 in case of success.
    
    A list of all error codes is given in section III.

  ..................................................................

  This distribution comes with an extension used to  support  access
  to  a  font's  kerning information.  The extension's types and API
  are defined in the file "ftxkern.h"

----------------------------------------------------------------------------


II. Functions:

  Here is a list of the core library's API.

  NOTE: A  function's  default  result  is  an  error code  of  type
        TT_Error;  a list  of error  codes is  given in  section III
        below.

        Some functions return integers or other types, in which case
        the result type is written with its description.

  ..................................................................

  TT_Init_FreeType();

     Initialize the engine.  This  call must be performed before any
     other function of FreeType is invoked.

  ..................................................................

  TT_Done_FreeType();

     Finalize the  engine.  This  calls destroys _all_  objects that
     were previously created and used with the engine

  ..................................................................

  TT_Open_Face( char*     fontpathname,
                TT_face*  face );

     This  call opens a  font file,  located by  'fontpathname', and
     returns a handle to the  newly corresponding face object in the
     handle '*face'.

     Example:

          error = TT_Open_Face( "c:\ttf\wingding.ttf", &face );
          if ( error )
            fprintf( stderr, "could not open face\n" );

     Note:
     The font file  can be a TrueType collection;  in this case, the
     engine will  always open the  first embedded font found  in the
     file.

  ..................................................................

  TT_Open_Collection( char*     collectionpathname,
                      int       fontIndex,
                      TT_Face*  face );

     This  call opens  one of  the font  files found  in  a TrueType
     collection.   The  file  is  selected through  the  'fontIndex'
     argument.

     Note  that to  know a  collection's number  of  embedded fonts,
     you'll have to:

       1 - open the first collection font with TT_Open_Face().

       2 - query the face's properties through
           TT_Get_Face_Properties().

     The number of embedded faces is then
     'properties->max_Faces + 1'.


     Example:

         TT_Face             face;
         TT_Face_Properties  properties;

         error = TT_Open_Face( "c:\ttf\sample.ttc", &face );
         if ( error ) { ...error .. }
         /* Open first embedded collection font */

         error = TT_Get_Face_Properties( face, &properties );
         if ( error ) { ...error .. }
         /* Get face metrics */

         printf( "There are %d fonts in this collection",
                 properties->max_Faces + 1 );

         TT_Close_Face( face );

         error = TT_Open_Collection( "c:\ttf\sample.ttc", 1,
                                     &face );
         if ( error ) { ...error .. }
         /* Open second font in collection */


     Note: If the file isn't a collection, 'fontIndex' must be zero.
           Otherwise, an error will be produced.

  ..................................................................

  TT_Get_Face_Properties( TT_Face              face,
                          TT_Face_Properties*  properties );

     Return  the  'face'  object's  '*properties'.   This  structure
     contains  various data,  like the  total number  of  glyphs and
     pointers to some mandatory TrueType tables.
     
     (See the definition of TT_Face_Properties in section I.)

  ..................................................................

  TT_Close_Face( TT_Face  face );

     Close a  given 'face' object.  This function  will also destroy
     all  the face's child  instances.  The  face's glyphs  won't be
     destroyed, however.

  ..................................................................

  TT_New_Instance( TT_Face       face,
                   TT_Instance*  instance );

     Create a new  instance object related to the  'face' object.  A
     handle to the newly created instance is returned in 'instance'.

     The default  instance resolution is 96dpi in  both vertical and
     horizontal direction; the default point size is 10pt.

  ..................................................................

  TT_Set_Instance_Resolution( TT_Instance  instance,
                              int          x_resolution,
                              int          y_resolution );

     Set  the target device  resolution for  a given  instance.  The
     values are expressed in dots  per inch (dpi).  A value of 96dpi
     is typical for an SVGA  display, 72dpi for a Macintosh one, and
     300 to 6000dpi for printers.


  ..................................................................

  TT_Set_Instance_PointSize( TT_Instance  instance,
                             int          pointsize );  

     Sets  the  point  size  for  a given  instance.   The  size  is
     expressed in 'points', where 1  point = 1/72 inch.  The default
     value is 10pt.

  ..................................................................

  TT_Set_Instance_Transform_Flags( TT_Instance instance,
                                   int         rotated,
                                   int         stretched );

     Set the transform flags for  a given instance.  These flags are
     passed to  the interpreter each  time a glyph is  loaded within
     the  instance.   Their role  is  to  notify  the glyph  hinting
     mechanism  that the resulting  glyph will  be transformed  in a
     special  way.   Setting one  of  these  flags  to true  usually
     disables hinting,  though this behaviour varies  with each font
     file.

     NOTE:
     The glyph loader doesn't perform the rotation or the stretching
     itself; this must be done explicitly by the client application.
     Use the function TT_Apply_Outline_Matrix() for that purpose.

  ..................................................................

  TT_Get_Instance_Metrics( TT_Instance           instance,
                           TT_Instance_Metrics*  imetrics );

     This call returns a given instance's current metrics.  They are
     returned  in the  'imetrics' structure,  which  contains, among
     other  things,  the  current   point  size,  ppem,  and  device
     resolution (horizontal and vertical).

  ..................................................................

  TT_Done_Instance( TT_Instance  instance );

     Close a given instance  object, destroying its associated data.
     Note that this is performed automatically when a face is closed
     on all its child instances.  However, explicit deallocation can
     help in freeing the memory used by the application earlier.

  ..................................................................

  TT_New_Glyph( TT_Face    face,
                TT_Glyph*  glyph );

     Create  a  new glyph  container  for  the  glyphs of  the  font
     described by the 'face' handle.   A pointer to the container is
     returned  in 'glyph'.   The  face  is said  to  be the  glyph's
     parent.
 
     Note  that a  glyph isn't  destroyed  when the  face object  is
     destroyed.  You have  to discard it manually through  a call to
     TT_Done_Glyph(),  or  automatically  when  closing  the  engine
     through TT_Done_FreeType().

  ..................................................................

  TT_Done_Glyph( TT_Glyph  glyph );

     Discard a glyph container.  This is also done automatically for
     all glyphs when closing the engine.

  ..................................................................

  TT_Load_Glyph( TT_Instance  instance,
                 TT_Glyph     glyph,
                 int          glyph_index,
                 int          load_flags );

     Load  and  process (scale  and/or  hint)  a  glyph at  a  given
     'instance' into the 'glyph' container.
     
     Note that  'glyph' and 'instance'  must have the  _same_ parent
     face object, or an error message will be returned.
     
     'glyph_index'  is the glyph's  index as  found in  the TrueType
     file.  It is _not_ a  character code (see the charmap functions
     below).
   
     'load_flags' is an integer  that specifies which operations are
     to be performed on the loaded glyph.  The following values/bits
     are used:
   
   
         TTLOAD_SCALE_GLYPH
   
            Indicates  that   the  glyph  must  be   scaled  to  the
            instance's  resolution.  The pixel  coordinates returned
            in  the glyph  outline  structure (see  below) are  then
            expressed in  fractional pixels represented  in the 26.6
            fixed  point   floating  format  defined   by  Apple  as
            'F26Dot6'.
   
            If scaling is disabled,  the coordinates returned in the
            outline structure are  integers, also called 'FUnits' by
            the TrueType specification.
   
   
         TTLOAD_HINT_GLYPH
   
            This flag is only valid  when scaling is on.  It informs
            the  loader   that  the  glyph  must   be  hinted  (i.e.
            grid-fitted  for optimal  display).   Note that  hinting
            will  occur only if  the instance's  transformations and
            metrics  allow  it  (for  example,  most  font  programs
            disable  hinting automatically  in case  of  rotation or
            stretching).

       NOTE:
       You can also use the constant TTLOAD_DEFAULT, which is simply
       the  union of  TTLOAD_SCALE_GLYPH  and TTLOAD_HINT_GLYPH  for
       most 'typical' loads.
  
  ..................................................................

  TT_Get_Glyph_Outline( TT_Glyph           glyph,
                        TT_Glyph_Outline*  outline );

     This  call returns  the glyph's  'outline'.  This  is  a simple
     structure which contains pointers  to the data used to describe
     an   outline  to   the  rasterizer.   See  the   definition  of
     TT_Glyph_Outline() in section I.

  ..................................................................

  TT_Get_Glyph_Metrics( TT_Glyph           glyph,
                        TT_Glyph_Metrics*  metrics );

     Extract  the glyph's metrics  and copy  them to  the '*metrics'
     structure.  Its format is described in section I.

     When the glyph has been  loaded without scaling, the values are
     expressed  in FUnits  (integers relative  to the  original font
     grid called the EM Square).

     When the  glyph has  been loaded _with_  scaling, which  is the
     default, the  values are expressed in fractional  pixels in the
     26.6 fixed  point float format  called F26Dot6 (where 1  unit =
     1/64th of a pixel).

  ..................................................................

  TT_Get_Glyph_Bitmap( TT_Glyph        glyph,
                       TT_Raster_Map*  bitmap,
                       TT_F26Dot6      x_offset,
                       TT_F26Dot6      y_offset );

     This call converts the vectorial glyph representation contained
     in the object handled by 'glyph' into a bitmap.

     The  target  bitmap  is  described  by  the  'bitmap'  pointer.
     Clipping will  be done if  necessary.  You can also  specify an
     offset   to  be  applied   before  the   scan-line  conversion;
     'x_offset'  and  'y_offset'  must  be expressed  in  fractional
     pixels (where 1 unit = 1/64th pixel).

     NOTE1:
       Choosing   non  integer  pixel   offsets,  i.e.,   values  of
       'x_offset' and 'y_offset' that  are not multiples of 64, will
       ruin the hinting performed  by the interpreter, and result in
       bad rendering at small sizes.

     NOTE2:
       The glyph's  point coordinates must be  scaled before calling
       this function.   Never call this  function with a  glyph that
       were loaded with no scaling!

  ..................................................................

  TT_Get_Glyph_Pixmap( TT_Glyph        glyph,
                       TT_Raster_Map*  pixmap,
                       TT_F26Dot6      x_offset,
                       TT_F26Dot6      y_offset );

     This call converts the vectorial glyph representation contained
     in  the object  handled  by  'glyph' into  a  pixmap (i.e.,  an
     8-bit/pixel map).  The result is an anti-aliased version of the
     glyph (a.k.a. font-smoothing).

     The target  pixmap is described by the  'pixmap' pointer.  Note
     that  its  width _must_  be  a multiple  of  4.   For a  pixmap
     definition and description, see Section I.

     As with  TT_Get_Glyph_Bitmap(), you  can specify offsets  to be
     applied before the rendering ('x_offset' and 'y_offset' must be
     expressed in fractional pixel coordinates).

     NOTE1:
       You  don't  need  to   supply  a  temporary  bitmap  for  the
       anti-aliaser.  The rasterizer uses its own scheme to optimize
       memory uses.

     NOTE2:
       The glyph's  point coordinates must be  scaled before calling
       this function.  This means that you should never call it with
       a glyph which has been loaded without scaling!

  ..................................................................

  TT_Apply_Outline_Matrix( TT_Glyph_Outline*  outline,
                           TT_Matrix*         matrix );

     Apply a simple transformation  matrix on a given outline.  This
     will  multiply each point  coordinate vector  by a  2x2 matrix,
     which coefficients are written in the 16.16 fixed float format.

     Rotation can be performed with this function.

     NOTE:
       This function takes an outline,  and not a glyph handle, as a
       parameter.  This 'feature'  lets you apply transformations on
       your own copies of glyphs.

  ..................................................................

  TT_Apply_Outline_Translation( TT_Glyph_Outline*  outline,
                                TT_F26Dot6         x_offset,
                                TT_F26Dot6         y_offset );

     Apply a simple translation on a given outline.

     NOTE:
       This function takes an outline,  and not a glyph handle, as a
       parameter.  This 'feature' lets you apply translation to your
       own copies of glyphs.

  ..................................................................

  int TT_Get_CharMap_Count( TT_Face  face );
  ^^^
     Return the number of character mappings present in the TrueType
     file described by the 'face' handle.  Returns zero if there are
     no mappings, and -1 when the handle is invalid.

  ..................................................................

  TT_Get_CharMap_ID( TT_Face  face,
                     int      charmapIndex,
                     short*   platformID,
                     short*   encodingID );

     Return the  platform ID  and platform-specific encoding  ID for
     the charmap numbered 'charmapIndex'  in the 'face' object.  The
     total  number of character  mapping tables  is returned  by the
     TT_Get_CharMap_Count() function described above.

  ..................................................................

  TT_Get_CharMap( TT_Face      face,
                  int          charmapIndex,
                  TT_CharMap*  charMap );

     Return a handle for  the character map number 'charmapIndex' of
     'face'.  The  handle is  placed in '*charMap'  and can  be used
     later for fast lookup with the TT_Char_Index() API.

     Charmap objects  are  automatically  destroyed  when their face
     object is destroyed.

  ..................................................................

  int TT_Char_Index( TT_CharMap  charMap,
  ^^^                int         charCode );

     Apply a charMap to translate a charCode into a glyph index that
     can be used to load and address a glyph in the TrueType file.

     The charmap handle can be obtained with TT_Get_CharMap().

  ..................................................................

  int TT_Get_Name_Count( TT_Face  face );
  ^^^
     Returns  the number  of name  strings  found in  a face's  name
     table.  This function  will return zero when there  are no name
     strings in the font file, and -1 if the face handle is invalid.

  ..................................................................

  TT_Get_Name_ID( TT_Face  face,
                  int      nameIndex,
                  short*   platformID,
                  short*   encodingID,
                  short*   languageID,
                  short*   nameID );

     Return the  ID of  a given name  string, indexed by  the number
     'nameIndex' in a  given face.  The name index  ranges from 0 to
     the value returned by TT_Get_Name_Count() minus one.

     Each  string  has  a  platformID,  encodingID,  languageID  and
     nameID, as defined by the TT specification.
     
     The platformID is typically in the 0..3 range.  Some font files
     have  invalid name table  entries; these  can be  detected from
     their platformID which is over 3.

  ..................................................................

  TT_Get_Name_String( TT_Face  face,
                      int      nameIndex,
                      char**   stringPtr,
                      int*     length );

     Return  a  name string's  address  and  length.   Note that  an
     invalid name table entry, detected  by a platformID > 3, always
     returns NULL for 'stringPtr' and a zero length.

     Note: the string belongs to  the face object, and should not be
           written to or freed by the client application.

  ..................................................................

  TT_Get_Kerning_Directory( TT_Face      face,
                            TT_Kerning*  directory );

     Queries the  kerning directory found  in a face object.   If no
     kerning  table  is  found  in  the  TrueType  file,  the  error
     TT_Err_Table_Is_Missing will be returned.

     You  can  access the  subtables  through  the  pointers of  the
     directory.  However,  by default, the directory  is only loaded
     when a  face object  is created.  You  must load  the subtables
     that interest you with a call to TT_Load_Kerning_Table().

     The layout  of all  kerning structures is  defined in  the file
     "lib/extend/apikern.h".  Both formats (0  and 2) are exposed by
     this API.

  ..................................................................

  TT_Load_Kerning_Table( TT_Face  face,
                         int      kern_index );

     Load the kerning subtable number 'kern_index' into memory.  The
     subtable can  be accessed through the pointers  provided by the
     kerning     directory,    obtained     from    a     call    to
     TT_Get_Kerning_Directory().

     Note that the interpretation of the kerning data is left to the
     client application.   Read the TrueType  specification for more
     information on kerning encoding.



III. Error Messages:

  Most functions return an error  code, typed to TT_Error.  A return
  value of zero indicates no error.  The error values are defined in
  the file 'freetype.h'.


  Error   Unprefixed             Error
  Code    Macro Name             Description          
  ------------------------------------------------------------------

  0x0000  Ok                       Successful function call.
                                   Always 0!

  ----------------- high-level API error codes ---------------------

  The following error codes are returned by the  high-level  API  to
  indicate an invalid client request.

  0x0001  Invalid_Face_Handle      An invalid face object handle was
                                   passed to an API function.

  0x0002  Invalid_Instance_Handle  An invalid instance object handle
                                   was passed to an API function.

  0x0003  Invalid_Glyph_Handle     An invalid glyph container handle
                                   was passed to an API function.

  0x0004  Invalid_CharMap_Handle   An invalid charmap handle was
                                   passed to an API function.

  0x0005  Invalid_Result_Address   An output parameter (a result)
                                   was given a NULL address in an
                                   API call.

  0x0006  Invalid_Glyph_Index      An invalid glyph index was passed
                                   to one API function

  0x0007  Invalid_Argument         An invalid argument was passed to
                                   one API function. Usually, this
                                   means a simple out-of-bounds
                                   error.

  0x0008  Could_Not_Open_File      The pathname passed doesn't point
                                   to an existing or accessible
                                   file.

  0x0009  File_Is_Not_Collection   Returned by TT_Open_Collection
                                   when trying to open a file which
                                   isn't a collection.

  0x000A  Table_Missing            A mandatory TrueType table is
                                   missing from the font file.
                                   Denotes a broken font file.

  0x000B  Invalid_Horiz_Metrics    The font's HMTX table is broken.
                                   Denotes a broken font.

  0x000C  Invalid_CharMap_Format   A font's charmap entry has an
                                   invalid format.  Some other
                                   entries may be valid though.

  0x0010  Invalid_File_Format      The file isn't a TrueType font or
                                   collection

  ----------------- memory component error codes -------------------

  0x0100  Out_Of_Memory            An operation couldn't be
                                   performed due to memory
                                   exhaustion.

  ----------------- file component error codes ---------------------

  0x0200  Invalid_File_Offset      Trying to seek to an invalid
                                   portion of the font file.
                                   Denotes a broken file.

  0x0201  Invalid_File_Read        Trying to read an invalid portion
                                   of the font file.  Denotes a
                                   broken file.

  0x0202  Invalid_Frame_Access     Trying to frame an invalid
                                   portion of the font file.
                                   Denotes a broken file.

  ----------------- glyph loader error codes -----------------------

  These errors are  produced by  the  glyph loader.  They denote  an
  invalid glyph record within the font file.

  0x0300  Too_Many_Points          The glyph has too many points to
                                   be valid for its font file.

  0x0301  Too_Many_Contours        The glyph has too many contours
                                   to be valid for its font file.

  0x0302  Invalid_Composite_Glyph  A composite glyph's description
                                   is broken.

  0x0303  Too_Many_Ins             The glyph has too many
                                   instructions to be valid for its
                                   font file.

  ----------------- byte-code interpreter error codes --------------

  These  error   codes  are  produced  by   the   TrueType byte-code
  interpreter.  They usually indicate a broken font file or a broken
  glyph within a font.

  0x0400  Invalid_Opcode         Found an invalid opcode in a
                                 TrueType byte-code stream.

  0x0401  Too_Few_Arguments      An opcode was invoked with too few
                                 arguments on the stack.

  0x0402  Stack_Overflow         The interpreter's stack has been
                                 filled up and operations can't
                                 continue.

  0x0403  Code_Overflow          The byte-code stream runs out of
                                 its valid bounds.

  0x0404  Bad_Argument           A function received an invalid
                                 argument.

  0x0405  Divide_By_Zero         A division by 0 operation was
                                 queried by the interpreter program.

  0x0406  Storage_Overflow       The program tried to access data
                                 outside of its storage area.

  0x0407  Cvt_Overflow           The program tried to access data
                                 outside of its control value table.

  0x0408  Invalid_Reference      The program tried to reference an
                                 invalid point, zone or contour.

  0x0409  Invalid_Distance       The program tried to use an invalid
                                 distance.

  0x040A  Interpolate_Twilight   The program tried to interpolate
                                 twilight points.

  0x040B  Debug_Opcode           The now invalid 'debug' opcode was
                                 found in the byte-code stream.

  0x040C  ENDF_In_Exec_Stream    A misplaced ENDF was encountered in
                                 the byte-code stream.

  0x040D  Out_Of_CodeRanges      The program tried to allocate too
                                 much code ranges (this is really an
                                 engine internal error that should
                                 never happen).

  0x040E  Nested_DEFS            Nested function definitions 
                                 encountered.

  0x040F  Invalid_CodeRange      The program tried to access an
                                 invalid code range.

  ----------------- internal failure error codes -------------------

  These error codes are produced if  an incoherent library state has
  been detected.   All of these reflect  a severe bug  in the engine
  (or a severe memory corruption  due to massive overwrites by  your
  application into the library's data)!

  If you do  encounter a font that   makes one of the  test programs
  produce such an error, please report it!

  0x0500  Nested_Frame_Access
  0x0501  Invalid_Cache_List
  0x0502  Could_Not_Find_Context
  0x0503  Unlisted_Object

  ----------------- scan-line converter error codes ----------------

  These  error codes are  produced  by  the raster  component.  They
  indicate that   an outline structure  was incoherently  set up, or
  that you're trying to render a horribly complex glyph.

  They should be _extremely_ rare, however.

  0x0600  Raster_Pool_Overflow   Render pool overflow. This should
                                 never happen in this release.

  0x0601  Raster_Negative_Height
                                 A negative height was produced.

  0x0602  Raster_Invalid_Value   The outline data wasn't set
                                 properly. Check that:
                                   points >= endContours[contours]

  0x0603  Raster_Not_Initialized
                                 You did not call TT_Init_FreeType!

  ----------------- engine extensions error codes ------------------

  The engine's extensions also provide their own error codes, within
  their own group:

  0x0A00  Invalid_Kerning_Table_Format
                                 A kerning subtable format was found
                                 invalid in this font.


--- end of apiref.txt ---
