
                        The FreeType Engine

                      Core Library User Guide

                                 or

    How to use the engine in your applications and font servers
                          by David Turner

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

                            Introduction


                         I. Basic Concepts:
  
                       1. Concepts
                       2. Handles
                       3. Conventions of use
                       4. Object classes

                          II. Extensions:

                     1. What is an extension?
                     2. Where to find them
                     3. Writing your own extension

                             Conclusion

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

Introduction:

This file has  been written to present the  FreeType core library to
would-be  writers  of  applications  and  font  servers.   It  first
describes the concepts on which the engine is based, then how to use
it to obtain glyph metrics, outlines and bitmaps.

The last part discusses the ability to add and use extensions to the
core library to get access to supplemental TrueType tables which are
not currently  provided by  the core engine.   If you would  like to
write your own extensions, read also the FreeType developer's guide.



I. Basic Concepts:


  1. Concepts:

    FreeType defines several  kinds of structures, called "objects",
    that  are used to  manage the  various abstractions  required to
    access and display fonts.

    In a care of good  encapsulation, these objects are not directly
    accessible from a client application.  Rather, the user receives
    a 'handle'  for each object it  queries and wants  to use.  This
    handle  is a  stand-alone reference;  it cannot  be used  like a
    pointer to access directly the object's data.


  2. Properties:

    It  is however  possible  to obtain  and  set object  properties
    through  several functions  of the  API.  For  example,  you can
    query  a face  object's properties  with only  a handle  for it,
    using the function TT_Get_Face_Properties().

    Note  that  the  data  will  be  returned  in  a  user-allocated
    structure,  but will also  contain pointers  addressing directly
    some data found within the object.

    A client application should  never modify the data through these
    pointers!  In order to set new properties' values, the user must
    always call  a specific  API to  do so, as  a certain  number of
    other related  data might not  appear in the  returned structure
    and imply various non-visible coherency and coercion rules.


  3. Conventions of use:

    o All API functions have  their label prefixed by 'TT_', as well
      as all external (i.e. client-side) types.


    o To  allow the  use  of  FreeType's  core  engine  in  threaded
      environments, nearly  all API functions return  an error code,
      which is always set to 0 in case of success.

      The error  codes' type is TT_Error,  and a listing  of them is
      given in the API reference (see "apiref.txt").

      Some functions do  not return an error code.   Their result is
      usually a value  that becomes negative in case  of error (this
      is  used for functions  where only  one kind  of error  can be
      reported, like an invalid glyph index).

      An important  note is that  the engine should not  leak memory
      when  returning an error,  e.g., querying  the creation  of an
      object  will allocate  several  internal tables  that will  be
      freed if a disk error occurs during a load.


    o A handle is acquired  through API functions labelled along the
      names:

        TT_Open_xxxx(), TT_New_xxxx()

      where 'xxxx' is the object's class (Face, Instance, etc).

      Examples:

        TT_Open_Face(), TT_Open_Collection(),
        TT_New_Instance(), TT_New_Glyph()


    o A handle is closed through an API labelled

        TT_Close_xxxx() or TT_Done_xxxx()

      where 'xxxx' is the object's class (Face, Instance, etc).

      Examples:

        TT_Close_Face(), TT_Done_Instance(), TT_Done_Glyph()


    o Properties are obtained through an API labelled

        TT_Get_xxxx_yyyy()

      where 'xxxx' is the object's class, and 'yyyy' its property.

      Examples:

        TT_Get_Face_Properties(), TT_Get_Instance_Metrics()
        TT_Get_Glyph_Outline(), TT_Get_Glyph_Bitmap()


    o Properties are set through an API labelled

        TT_Set_xxxx_yyyy()
          
      where 'xxxx' is the object's class, and 'yyyy' its property.

      Examples:

        TT_Set_Instance_Resolutions(),
        TT_Set_Instance_CharSize()


  4. Object Classes:

    The following object classes are  defined in this release of the
    engine:

    o The Engine objects:

      The FreeType library can be built to be completely re-entrant,
      even though its default build doesn't support threads (more on
      this in the developer's guide).

      As a consequence, it is  possible to open several instances of
      the library, called 'engines'.  Each engine has its own set of
      current  objects (faces,  instances,  etc.), and  there is  no
      sharing between them.

      The idea  is that  the library could  be compiled as  a shared
      DLL, and then  be able to provide several  distinct engines to
      independent  client applications.  In  this case,  each client
      program must create its  own engine with TT_Init_FreeType() to
      hold its data.

      Closing  an  engine  will  destroy  _all_  objects  that  were
      allocated  since its  opening, releasing  all  resources etc.,
      with the exception of user-allocated outline objects.


    o The Face objects:

      A face contains the data that is specific to a single TrueType
      font file.   It presents information common to  all glyphs and
      all point sizes like font-specific metrics and properties.

      You can open a face object  by simply giving a pathname to the
      TrueType file.   You can later close (i.e.,  discard) the face
      object.

      You  can  also open  a  single  face  embedded in  a  TrueType
      collection.

      See also:

        TT_Open_Face(), TT_Open_Collection(), TT_Close_Face(),
        TT_Get_face_Properties()


    o The Instance objects:

      An instance  is also called  a 'pointsize' or a  'fontsize' in
      some  windowing systems.   An instance  holds  the information
      used to  render glyphs on a  specific device at  a given point
      size; it is always related to an opened face object.

      For instance, if you want to generate glyphs for text from the
      same typeface at 'sizes' of 10  and 12 points, all you need is
      one  face  object,  from  which  you'll  create  two  distinct
      instances.
        
      A device is defined by its horizontal and vertical resolution,
      usually specified in  dots per inch (dpi).  A  point size is a
      scaling number, given as  _absolute_ values in points, where 1
      point = 1/72 inch.

      The 'pixel' size,  also known as the 'ppem'  value (for Points
      Per EM square) is computed from both the device resolution and
      the point size.  It determines the size of the resulting glyph
      bitmaps on your screen or sheet of paper.

      The default device resolution for any new instance is 96dpi in
      both  directions,  which  corresponds  to  VGA  screens.   The
      default point size is 10pt.   The high-level API allows you to
      change this whenever you want for any given instance object.

      Note that closing a face object will automatically destroy all
      its child instances (even though you can release them yourself
      to free memory).

      See also:

        TT_New_Instance(), TT_Done_Instance(),
        TT_Get_Instance_Metrics(), TT_Set_Instance_Resolutions(),
        TT_Set_Instance_Pointsize()


    o The Glyph objects:

      A Glyph  object is a  _container_ for the data  that describes
      any  glyph of  a given  font.   This means  that it  typically
      holds:

      - glyph  metrics  information, like  bounding  box or  advance
        width.

      - outline arrays sized large enough to hold any glyph from the
        face.   This  size is  extracted  from  the face's  internal
        'maxProfile' table to optimize memory costs.

      - other important  parameters related to  the 'fine' rendering
        of   the   glyphs.     This   includes   things   like   the
        dropout-control mode used at low sizes.

      - and it doesn't contain a bitmap or a pixmap!


      A glyph  object is used to  load, hint and  rasterize a single
      glyph, as taken from the font file.

      See also:

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


    o The Character Map (CharMap) handle:

      Glyphs  can  be indexed  in  a  TrueType  file in  any  order,
      independently of  any standard character  encoding, like ASCII
      or Unicode.  For this reason, each file comes with one or more
      character mapping tables, used  to translate from one specific
      encoding's charcodes to font glyph indexes.

      There  are  many  encoding   formats,  and  each  one  can  be
      distinguished by two values:

      - its platform ID
      - its platform-specific encoding ID

      Their  values are  defined in  the TrueType  specification and
      won't  be commented there.   The FAQ  lists the  most commonly
      used (platform:encoding) pairs.

      It  is  possible  to  enumerate  the charmaps  provided  by  a
      TrueType font and to use any of these to perform translations.

      The charmaps are  loaded in memory only on  demand to save the
      space taken  by the maps that  are not needed  on your system.
      They are part of the face object, however.

      This means that even though  a charmap can be accessed through
      a handle (obtained  through the TT_Get_CharMap() function), it
      isn't a  stand-alone object.  For  example, you never  need to
      de-allocate it; this is  done automatically by the engine when
      its face object expires.

      See also:

        TT_Get_CharMap_Count(), TT_Get_CharMap_ID(),
        TT_Get_CharMap(), TT_Char_Index().


    o The Outline Objects:

      An outline is a vector  representation of a glyph.  It is made
      of several  control points joined by line  segments and bezier
      arcs, themselves  gathered in closed  paths called "contours".
      The outline have also  several flags, or attributes, which are
      used by  the scan-line converter to select  the best rendering
      algorithms to convert the glyph's bitmap.

      Unlike  other  objects in  FreeType,  outlines aren't  managed
      through handles,  but directly with  the structure TT_Outline,
      defined  for   client  applications.   Each   glyph  container
      contains an outline sized large  enough to hold any glyph from
      its  parent  face.  Client  applications  can  access it  with
      TT_Get_Glyph_Outline().  However, one  can also create its own
      outlines     if    needed     with     TT_New_Outline()    and
      TT_Clone_Outline().

      Note  that  user-created  outlines  are  NOT  tracked  by  the
      library.  Hence, the client  must release them itself with one
      or more calls to TT_Done_Outline().

      A  various number  of methods/operations  are defined  for the
      outline class to simplify its management.


      IMPORTANT NOTE: **********************************************
        
        The  definition  of TT_Outline  may  change  in the  future.
        Developers  are  thus  advised  to always  use  the  outline
        methods provided  by the API rather than  reading or setting
        data themselves.

      **************************************************************
        
      See also:

        TT_New_Outline(), TT_Clone_Outline(), TT_Copy_Outline(),
        TT_Done_Outline(), TT_Get_Outline_BBox(),
        TT_Get_Outline_Bitmap(), TT_Get_Outline_Pixmap(),
        TT_Translate_Outline(), TT_Transform_Outline()


    o Bitmaps and Pixmaps:

      One very important aspect of  FreeType is that it is unable to
      create  bitmaps on  its  own.   Rather, it  is  to the  client
      application to do  it, and pass a reference, in  the form of a
      TT_Raster_Map,  to the scan-line  converter (the  component in
      charge of generating bitmaps from outlines).

      Hence the importance of the TT_Raster_Map structure, which
      layout is:

        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;


      And where:

      - 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 for
                   pixmaps!
    
        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.)
    


II. Step-by-step Example:

  Here is an example to show, step by step, how a client application
  can  open a  font file,  set one  or several  instances,  load any
  glyph, then render it to a bitmap.

  a. Initialize the engine:

    This is the first thing to do.  You need to initialize an engine
    through a call to TT_Init_FreeType().  This function will set up
    a various number of structures needed by the library.

    This allocates about 68kByte,  of which 64kByte are dedicated to
    the scan-line  converter's "render  pool", a workspace  used for
    bitmap generation.  Note that even though this space is bounded,
    the raster is able to render a glyph to any size or bitmap, even
    horribly huge ones.

    NOTE: You can reduce  the  size  of this  pool by  modifying the
          constant RASTER_RENDER_POOL  in the file  'ttraster.c'.  A
          smaller  pool will  result  in slower  rendering at  large
          sizes.  Take care of  never assigning a value smaller than
          4kByte however, as bugs may start to lurk in!

    Example:

      TT_Engine  engine;
      error = TT_Init_FreeType( &engine );
      if (error)
      {
        printf( "could not create engine instance\n");
        ...
      }


  b. Init the extensions you need:

    FreeType  provides   several  extensions,  which   are  optional
    separately  compilable   components  which,  adding   some  rare
    features to the engine and its API.

    You  need to explicitly  initialize the  extensions you  want to
    use.   Each extension must  provide an  initialization function,
    following the naming convention:

      TT_Init_xxxxx_Extension( engine );

    where 'xxxxxx' is the extension's "kind".

    Example:

      error = TT_Init_Kerning_Extension( engine );
      if ( error )
        ...


  c. Open the font file:

    There are  two ways to open  a font face, depending  on its file
    format:

    - If  it's a TrueType  file (ttf),  you can  simply use  the API
      named  TT_Open_Face(),  which  takes  the file's  pathname  as
      argument, as well as the address of the returned face handle.

      Check  the returned error  code to  see if  the file  could be
      opened and accessed successfully.

        TT_Face  face;  /* face handle */
        error = TT_Open_Face( engine, "/fonts/arial.ttf", &face );
        if ( error )
        {
          printf( "could not open the file\n" );
          ...
        }

    - If the  font is embedded  in a TrueType collection  (ttc), you
      can use  the API named TT_Open_Collection(),  which takes also
      the font's index within the collection's directory.

        TT_Face  face;  /* face handle */

        /* Load the collection's second face (index=1) */
        error = TT_Open_Collection( engine, "/fonts/mingli.ttc",
                                    1, &face );
        if ( error )
        {
          printf( "could not open the file\n" );
          ...
        }

    - Finally, when you do not  know the number of faces embedded in
      a TrueType collection, the following technique can be used:

      o Call TT_Open_Face()  with  the  collection  file's pathname.
        This  API recognizes  collections  automatically and  always
        return a handle for its first embedded font.

      o Get the  face's properties through TT_Get_Face_Properties().
        These contain, among other things, the total number of fonts
        emebdded in the collection, in its field 'num_Faces'.

          TT_Face             face;  /* face handle     */
          TT_Face_Properties  props; /* face properties */
    
          /* open the first collection font */
          error = TT_Open_Face( engine, "/fonts/mingli.ttc",
                                &face );
          if ( error )
          {
            printf( "could not open the file\n" );
            ...
          }
    
          /* Get the face properties */
          TT_Get_Face_Properties( face, &props );
    
          /* Now print the number of faces */
          printf( "there are %d faces in this collection file\n",
                  props->num_Faces );


  d. Create an instance from the face object:

    You must create an instance  (also known as a 'pointsize') which
    contains  information  relative to  the  target output  device's
    resolutions and a given point size.

    o The instance object is created through TT_New_Instance():

        TT_Instance  instance;
        error = TT_New_Instance( face, &instance );
        if ( error )
        {
          printf( "could not create instance\n" );
          ...
        }

      TECHNICAL NOTE: Creating  a  new  instance  executes its  font
                      program.  This can fail if the font is broken.
                      Never assume that the error code returned here
                      is always 0.

    o You  must set  the instance's properties  to suit  your needs.
      These   are  simply  its   device  resolutions,   set  through
      TT_Set_Instance_Resolutions(), and its point size, set through
      TT_Set_Instance_CharSize():

        /* set the target horizontal and vertical resolution to */
        /* 300dpi in each direction (typically for a printer)   */
        /* A fresh instance's default resolutions are 96dpi in  */
        /* both directions.                                     */
        error = TT_Set_Instance_Resolutions( instance, 300, 300 );
        if ( error )
        {
          printf( "could not set resolution\n" );
          ...
        }

        /* Now set the point size to 12 pts.  Default is 10pt.   */
        /* Don't forget that the size is expressed in 26.6 fixed */
        /* float format, so multiply by 64...                    */
        error = TT_Set_Instance_CharSize( instance, 12*64 );
        if ( error )
        {
          printf( "could not set point size\n" );
          ...
        }

      TECHNICAL NOTE: These  calls  may  execute  the   font's  prep
                      program,  which  can  fail  when the  font  is
                      broken.   Never assume  that  the error  codes
                      returned there are always successful.

    o You can  also set the instance's transformation  flags to tell
      the  glyph loading  function that  you're going  to  perform a
      transformation (like rotation or slanting) on the glyph.  Note
      that the glyph loader  doesn't perform the transformation.  It
      only  informs the  glyphs' hinting  instruction  streams about
      these  flags which  may use  it to  disable or  enable various
      features (grid-fitting, drop-out control etc).

      Use e.g.

        TT_Set_Instance_Transforms( FALSE, TRUE );

      to indicate that you're going to stretch, but not rotate, this
      instance's glyphs.  Default is, of course, both FALSE.

      **************************************************************

        RELEASE NOTE: With FreeType 1.1, setting these flags doesn't
                      work and produces errors during glyph loading.
                      You should not use  them until a later release
                      that fixes this.


  e. Create a glyph container:

    You need a  glyph object to serve as a  container for the glyphs
    you want to load from the face.  This is done simply by

      TT_Glyph  glyph;  /* glyph object handle */
      error = TT_New_Glyph( face, &glyph );
      if ( error )
      {
        printf( "could not create glyph\n" );
        ...
      }


  f. Find your platform's character mappings:

    Each  font file  can come  with  one or  more character  mapping
    tables, used to  convert char. codes to glyph  indexs.  You must
    know the values of  the "platformId" and "encodingID" defined in
    the     TrueType    specification     for     your    platform's
    charcode/codepage.   For example,  Windows  Unicode encoding  is
    (platform:3,encoding:1),     while      Apple     Unicode     is
    (platform:0,encoding:0).    Both  formats  differ   in  internal
    storage  layout and  can  be used  transparently  with the  same
    inputs with FreeType.

    The  function  TT_Get_CharMap_Count()   returns  the  number  of
    character mappings  present in a  face.  You can  then enumerate
    these with the  function TT_Get_CharMap_ID().  Once you've found
    the  mapping that  masp your  platform, use  TT_Get_CharMap() to
    return a TT_CharMap handle that  will be used later to get glyph
    indexs.


  g. Load the glyph:

    The  glyph  loader is  easily  queried through  TT_Load_Glyph().
    This API function takes several arguments:

    o An  instance  handle  to  specify  at  which  point  size  and
      resolution the loaded glyph should be scaled and grid-fitted.

    o A  glyph container, used to  hold the glyph's  data in memory.
      Note that the instance and the glyph must relate to the _same_
      font file.  An error would be produced immediately otherwise.

    o A  glyph index,  used to reference  the glyph within  the font
      file.  This  index is not a platform  specific character code,
      and  a character's  glyph  index  may vary  from  one font  to
      another.  To  compute glyph indexes from  character codes, use
      the   TT_CharMap   handle  created   in   section  (f.)   with
      TT_Char_Index().
        
      We  strongly  recommend  using  the Unicode  charmap  whenever
      possible.

    o A load  mode, indicating  what  kind  of operations  you need.
      There are only two defined for the moment:

        TTLOAD_SCALE_GLYPH:

          When set,  this flag indicates that the  loaded glyph will
          be scaled according to  the instance specified as argument
          to  fractional  pixel  coordinates  (26.6).  If  not,  the
          coordinates will  remain integer FUnits.   Please refer to
          the TrueType  specification and the  FreeType header files
          for more details on the 26.6 format and other data types.

        TTLOAD_HINT_GLYPH:

          This flag  is only  in effect when  the TTLOAD_SCALE_GLYPH
          flag is  set.  It  indicates that the  glyph must  also be
          'hinted',  or 'grid-fitted'  for  better display  results.
          Note that this  also means that the glyph  metrics will be
          grid-fitted, including the bounding box.

      You  can 'or'  the flags  simply.  As  most  applications will
      require both  flags to be set, the  constant TTLOAD_DEFAULT is
      defined as:

        #define TTLOAD_DEFAULT  (TTLOAD_SCALE_GLYPH | \
                                 TTLOAD_HINT_GLYPH )


      Example:

        error = TT_Load_Glyph( instance, glyph, 36,
                               TTLOAD_DEFAULT );
        if ( error )
        {
          printf("could not load the glyph\n");
          ...
        }


  h. Query glyph properties:

    You're then able to query various glyph properties:

    o The    glyph     metrics    can     be    obtained     through
      TT_Get_Glyph_Metrics().   The  data  returned in  the  metrics
      structure is:

      - the glyph's left side bearing (bearingX)
      - the glyph's top side bearing (bearingY)
      - the glyph's advance width (advance)
      - the glyph's bounding box (bbox)

      These values are expressed in  26.6 pixel units when the glyph
      was loaded with scaling, or in FUnits if not.

    o The    glyph      outline    can     be    queried     through
      TT_Get_Glyph_Outline().   This can  be useful  to  process the
      points  coordinates (e.g.,  applying  stretching or  rotation)
      with     functions    like     TT_Apply_Outline_Matrix()    or
      TT_Apply_Outline_Translation().  Note  that these functions do
      not recompute a glyph's metrics after the transformation!

      The  outline's   structure  is  described   in  the  reference
      "apiref.txt".

      A bitmap or pixmap for the  glyph can be queried with the APIs
      TT_Get_Glyph_Bitmap()    and   TT_Get_Glyph_Pixmap().    These
      functions take  a glyph  handle as an  argument, as well  as a
      bitmap/pixmap description block and two offsets.

      The target  map is  described through a  TT_Raster_Map object,
      which   structure   is   defined   in   the   reference   (see
      "apiref.txt").  The offsets are given in the same units as the
      points coordinates  and glyph metrics: 26.6 pixel  units for a
      scaled glyph, and FUnits for an unscaled one.

      IMPORTANT TECHNICAL NOTE: When the  glyph has  been scaled and
                                hinted,   the   offsets  _must_   be
                                multiples of  64 (i.e. integer pixel
                                offsets).    Otherwise,   you  would
                                simply ruin  the grid fitting (which
                                usually results in ugly glyphs).

      Example:

        TT_Glyph_Metrics  metrics;
        TT_Outline        outline;
        TT_Raster_Map     bitmap;


        TT_Get_Glyph_Metrics( glyph, &metrics );
        TT_Get_Glyph_Outline( glyph, &outline );

        /* set up the bitmap */
        ...
        TT_Get_Glyph_Bitmap( glyph, &bitmap, 0, 0 );


  i. When you're done:

    o You can close any font face object with TT_Close_Face().  This
      call  will automatically discard  its child  instances, glyphs
      and charmaps.

    o  You  can  also  close  the  engine  with  a  single  call  to
      TT_Done_FreeType().   This will  simply release  _all_ objects
      that  were   previously  allocated  (with   the  exception  of
      user-created outlines),  and close all font files,  as well as
      extensions that were inited for it.



III. Extensions:

  1. What is an extension?

    FreeType  allows you  to  access a  various  number of  TrueType
    tables, as well as to render individual glyphs.  However:

    1. it   doesn't  perform   some   high-level  operations,   like
       generating a string text from many individual glyphs.

    2. it doesn't perform kerning (which can be needed by operations
       mentioned in item 1).

    3. it doesn't  give access to  all the defined  TrueType tables,
       especially the optional ones.

    While point  1 is a feature  that will never  go into FreeType's
    core engine, which  goal is to provide easy  access to font data
    and rendering _individual_ glyphs, point 2 and 3 can be added to
    the engine's features through extensions.

    An extension  is simply a small  piece of code  that extends the
    engine's  abilities and  APIs.   It is  possible  to extend  the
    engine  without  touching  the   core's  source  code,  this  is
    described in chapter 3 below.


  2. The two kinds of extensions:

    There  are  basically two  kinds  of  extensions, which  require
    different implementations.


    a. API extensions:

      An  API  extension is  a  set  of  functions that  extend  the
      FreeType core  API to give  access to tables that  are already
      loaded by the engine, but not provided for now.  An example of
      such data can be:

      - the horizontal metrics table (HMTX)
      - the gasp table

      This kind of extension is made of:

      o an API extension header file, following the usage convention
        introduced here (all labels  prefixed with 'TT_'), and which
        will  be included  by  the  clients which  want  to use  the
        extension.   By  convention, such  header  names begin  with
        'ftx' (for FreeType eXtension).

        Examples: ftxgasp.h, ftxhtmx.h
  
      o One or more functions used to give access to the tables that
        are already loaded and  managed by the engine.  They usually
        only  copy pointers  to the  target structure  given  by the
        client application since these structures are not accessible
        through the 'normal' API.   An API extension doesn't need to
        be initialized before being used.


    b. engine extensions:

      It can be  sometimes useful to load and  manage several tables
      that are not considered  by the core engine.  These extensions
      need to  provide additional  functions to fit  into FreeType's
      internal object  management model, and  are more sophisticated
      than API extensions.

      An example  is given in  this distribution to  provide kerning
      support  (or more  technically spoken,  access to  the kerning
      tables found within the TrueType files).  It is made of:

      o An API  extension  providing  new interfaces  to  the client
        applications that need it.  See the file "ftxkern.h".

      o A specific  implementation,  providing  services  to create,
        load,  and manage kerning  tables as  additional parts  of a
        face  object.  In  the  case of  kerning,  the directory  of
        tables  is  loaded  when  the  face is  opened,  and  tables
        themselves  are  fetched  from  the file  on  demand.   This
        implies several  'hooks' in the core engine.   See the files
        "ttkern.h"  and   "ttkern.c".   These  are   called  'engine
        extensions'.

      o A   specific  extension  initialization   function,   namely
        TT_Init_Kerning_Extension(),  that must  be called  after an
        engine's  creation, and before  any face  object allocation.
        This  function  will  "register"  the extension  within  the
        engine and make its API workable.


  3. Writing your own extensions:

    As it  was suggested earlier,  writing an engine extension  is a
    delicate process,  as the additional code must  follow a certain
    number of  design rules,  presented in the  FreeType developer's
    guide.  There  is also an  extension writer's guide in  the file
    "extend.txt".

    ****************************************************************

    RELEASE NOTE: FreeType 1.1 doesn't provide the file "extend.txt"
                  yet...

    By writing your  own extensions, it will be  possible to support
    more advanced TrueType formats like TrueType GX or OpenType in a
    near future, without having to torture the engine core source at
    each iteration.

    If you  encounter some difficulties  when trying to  create your
    own extension,  please read the core source  file carefully, and
    in the  event that you may  need changes that are  not fitted to
    the current extension mechanism,  do not hesitate to contact the
    authors at 'freetype-devel@lists.lrz-muenchen.de'.

    
Conclusion:

    This is  the second  version of this  document, updated  for the
    FreeType 1.1 release.  The  engine source code has become rather
    stable since  the beta, and its quality  compares very favorably
    to Windows  and the Macintosh.   Its internals will  continue to
    change, though  very slowly, even  if the API isn't  expected to
    grow much in a near future.

    There is still work to do, however, as the need for a simple and
    effective way to  deal with internationalization in applications
    calls  for the  support of  non-roman text  layouts  and metrics
    (e.g., support for  vertical and right-to-left written scripts),
    or even embedded bitmaps (present  in some faces for some glyphs
    which turn out to be too complex to hint correctly at some small
    sizes).  These features will  most probably be supported through
    extensions, and  won't need major  changes and re-design  of the
    engine.

    Then,  the engine  is really  a glyph-oriented  TrueType driver.
    Its purpose  is to open and  manage font files in  order to load
    single glyphs and render them  as cleanly as possible.  A number
    of   features,  important  to   developers,  like   text  string
    rendering, font mapping and underlining/stroking, to name a few,
    aren't provided there even though they'd be highly appreciated.
   
    We hope you  have success and fun using  this engine.  Much time
    has  been  taken to  make  it  one of  the  best  in its  genre.
    Remember that it is not intended to be a complete font server or
    text rendering library, but a  pretty solid base for these kinds
    of applications, as well as others.

    We would like  you to report the bugs  you find, _after_ reading
    the current bug report at our web page:

      http://www.freetype.org



    We thank you for your time and consideration.

                       David Turner, Robert Wilhelm, Werner Lemberg,
                                 and all the FreeType enthusiasts...


--- End of user.txt ---
