freetype2/docs/DESIGN

The Design of FreeType 2.0
==========================

Introduction:

  This short document presents the design of version 2 of the FreeType
  library. It is a must read for anyone willing to port, debug or hack
  the FreeType sources.


I. Goals :

  FreeType 2 was designed to provide a unified and universal API to
  manage (i.e. read) the content of font files.

  Its main features are :


    - A FORMAT-INDEPENDENT HIGH-LEVEL API

        Used to open, read and manage font files.


    - THE USE OF PLUGGABLE "FONT DRIVERS"

        Each font driver is used to support a given font format. For
        example, the default build of FreeType 2 comes with drivers for the
        TrueType and Type 1 font formats.

        Font drivers can also be added, removed or upgraded at *runtime*,
        in order to support more font formats, or improve the current ones.

        Each font driver also provides its own "public interface" to client
        applications who would like to use format-specific features.

   
    - THE USE OF PLUGGABLE "RASTERS"

        A raster is a tiny module used to render a glyph image
        into a bitmap or anti-aliased pixmap. Rasters differ in their
        output quality (especially with regards to anti-aliasing), speed
        and memory usage.

        An application can also provide its own raster if it needs to.

        
    - HIGH PORTABILITY AND PERFORMANCE

        The FreeType source code is written in industry-standard ANSI C.

        Moreover, it abstracts memory management and i/o operations within
        a single module, called "ftsystem". The FreeType build system tries
        to auto-detect the host platform in order to select its most
        efficient implementation. It defaults otherwise to using the
        standard ANSI C Library.
        
        Note that, independently of the host platform and build, an
        application is able to provide its own memory and i/o routines.

        This make FreeType suitable for use in any kind of environment,
        from embedded to distributed systems.


II. Components Layout :

  FreeType 2 is made of distinct components which relate directly to the
  design described previously:


  1. THE BASE LAYER:

     The base layer implements the high-level API, as well as provide
     generic font services that can be used by each font driver.
     

  2. THE FONT DRIVERS:

     Each font driver can be registered in the base layer by providing
     an "interface", which really is a table of function pointers.

     At build time, the set of default font drivers is selected. These
     drivers are then compiled and statically linked to the library.

     They will then be available after the library initialisation.


  3. THE RASTERS:

     FreeType 2 provides the ability to hook various raster modules into
     its base layer. This provides several advantages :

       - different systems mean different requirements, hence the need for
         flexibility.

       - for now, FreeType 2 only supports glyph images stored in the
         following formats :

           * bitmaps
           * gray-level pixmaps
           * monochrome vectorial outlines (using bezier control points)

         should a new "technology" come for glyph images, it is possible
         to write a new raster for it, without altering the rest of the
         engine. Some examples could be :

           * multi-colored vectorial outlines
           * on-the-fly rendering of TeX's MetaFonts !!



  4. THE SYSTEM MODULE "FTSYSTEM":

     The system module is used to implement basic memory and i/o management
     services. By default, it uses the ANSI C library, but some replacements
     are also provided (and automatically selected by the build system) when
     available.

     As a simple example, the unix build uses memory-mapped files to read
     font files, instead of the slow ANSI "fopen/fseek/fread". This results
     in tremendous performance enhancements.

     Note that, even if the build system chooses an implementation for
     "ftsystem" at compile time, an application is still able to provide
     its own memory or i/o routines to the library at runtime.




  5. THE "INIT" LAYER:

     A tiny module used to implement the function FT_Init_FreeType.

     As its name suggests, it is responsible for initialising the library,
     which really means the following :

        - bind the implementation of "ftsystem" that best matches the
          host platform to the library. This choice can be overriden
          later by client applications however.

        - register the set of default font drivers within the base layer.
          these drivers are statically linked to the library. Other drivers
          can be added at runtime later through FT_Add_Driver though..

        - register the set of default rasters. Client applications are
          able to add their own rasters at runtime though.

     The details regarding these operations is given in the document
     named "FreeType Build Internals"



III. Objects Layout :

  Even though it is written in ANSI C, the desing of FreeType 2 is object
  oriented, as it's the best way to implement the flexible font format
  support that we wanted.

  Indeed, the base layer defines a set of base classes that can be derived
  by each font driver in order to support a given format. The base layer
  also includes many book-keeping routines that need not be included in the
  drivers.

  The base classes are the following:


  1. FACE OBJECTS:

    As in FreeType 1.x, a face object models the content of a given font
    that isn't dependent on a given size, transformation or glyph index.

    This includes, for example, the font name, font style(s), available
    charmaps and encodings, and all other kinds of data and tables that
    help describe the font as a whole.


  2. SIZE OBJECTS: (previously known as INSTANCE OBJECTS in 1.x)

    A face object can have one or more associated size objects. A Size
    object is used to stored the font data that is dependent on the current
    character size or transform used to load glyphs.

    Typical data in a size object include scaled metrics, factors, and
    various kind of control data related to grid-fitting. The size object
    is changed each time the character size is modified.


  3. GLYPH SLOT OBJECTS:

    Each face object has one "glyph slot", which is a simple container
    where individual glyph images can be loaded and processed.

    The glyph image can be stored in the following formats in the glyph
    slot :

        - monochrome bitmaps
        - gray-level pixmaps
        - vectorial glyph outlines (defined with bezier control points)

    Note that a module, called the "raster" is provided to convert vector
    outlines into either monochrome or anti-aliased bitmaps. The outline
    is also directly accessible and can be walked or processed freely by
    client applications.

    more glyph images formats can be defined, but they will require
    a specific raster module if one wants to display them on a typical
    display surface.

  4. CHARMAP OBJECTS:

    A charmap is used to convert character codes, for a given encoding,
    into glyph indices. A given face might contain several charmaps, for
    example, most TrueType fonts contain both the "Windows Unicode" and
    "
    it is not rare to see TrueType fonts with both the
    "Windows Unicode" and "Apple Roman" charmap